← All tasks
cppOHF-Voice/piper1-gpl #258Not a task: already works

Clang-Format custom target executed every CMake build

envgap__OHF-Voice__piper1-gpl-258

01 / FAILURE SIGNATURE

As reported upstream

No identifying execution failure has been captured.
Not a benchmark task.
  • The project already builds and runs before the fix, so there is nothing to repair.

02 / ENVIRONMENT RECIPE

Base commit
ffb62233b04dd0b04f005cd7c1f879eb9b0889fd
Manifest
libpiper/CMakeLists.txt
Reproduce
Awaiting issue-specific recipe
Run under trace
Awaiting a meaningful runtime command

03 / ORIGINAL ISSUE TEXT

OHF-Voice/piper1-gpl #258 · read the original issue
# Every time a CMake build is executed `clang-format` is executed.

## Problem

The execution of `clang-format` can potentially screw up your code when you have a type your code and a scope bracket is not at the correct position.
> Personal experience with that.

It can not be tolerated that building your project modifies the source code this is NOT DONE.

The actual problem is located at  [libpiper/CMakeLists.txt:233](https://github.com/OHF-Voice/piper1-gpl/blob/4bfd11c5b5998660c52aaa743c4fa05717104e98/libpiper/CMakeLists.txt#L233) where the added custom target `format` is made dependent on target `piper`.

> How can this be missed?!

## C++ Community Recommendations

The C++ community universally considers automatically running `clang-format` during a mandatory build step to be a harmful anti-pattern. Below is an itemized breakdown explicitly dismissing the current implementation, followed by the recommended industry alternatives.

### Why the Current Implementation is Explicitly Dismissed:

* **Violates Build System Idempotency**: A build system’s core job is to consume source files to generate binaries. It must never act as a write-operation on the very source code it is currently compiling.
* **Corrupts Unfinished Logic**: Forcing formatting on local compiles can permanently corrupt a developer's code structure if they trigger a build while mid-type or debugging syntax/bracket errors.
* **Destroys Editor Undo History**: Overwriting disk files externally during a build breaks the file buffer state in many IDEs, completely wiping out the developer's local undo/redo stack.
* **Pollutes Git Working Directory**: Automatic formatting unpredictably modifies files that the developer did not intend to touch, creating messy, unstaged diffs that disrupt version control workflows.
* **Triggers Infinite Recompilation Loops**: Modifying source file timestamps *during* the build invalidates build graph caches, frequently forcing tools like Make or Ninja to re-trigger heavy incremental compiles.

### Preferred Industry Alternatives:

* **Optional Standalone CMake Target**: Provide a formatting target that must be explicitly triggered by choice (e.g., `cmake --build . --target format`) rather than chaining it to the primary build graph.
* **Continuous Integration (CI) Linting**: Offload formatting checks to the server during Pull Requests. The CI runner verifies formatting via `clang-format --dry-run --Werror`, leaving the local workspace entirely untouched.
* **Git Pre-Commit Hooks**: Utilize framework hooks (like `pre-commit`) to format modified lines right when a developer initiates a `git commit`, locking in style consistency safely before pushing code.
* **Editor and IDE Integration**: Delegate formatting to the developer's workstation. Modern IDEs handle "Format on Save" natively within the application, seamlessly preserving undo/redo histories.

Continue on GitHub ↗

04 / LABELS

Labels from the report text only; not yet run

No supported category has been assigned.

Label rules and the text that matched
[]