[alliepiper]

Adds configuration and precommit hooks for gersemi, a cmake formatter:

https://github.com/BlankSpruce/gersemi

I've reviewed all of the changes in this PR and am pleased overall with the results. The upstream maintainer has been responsive to questions, suggestions, and issues I've had in this process.

We have a total of 135 files with 20816 lines of CMake in our repo, and there were very few instances where I felt the need to manually format using the # gersemi: [off|on] hints -- pretty much all of them were for COMMAND argument formatting which I don't expect a formatter to get correct.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[bernhardmgruber]

I love this for the sake of having consistent formatting!

I would also love if it wouldn't expand the code vertically so much. Looking at the changed LOCs, we expand by roughly 50%. That's a lot. Are there any options to keep the code more dense?

[alliepiper]

Are there any options to keep the code more dense?

Dense CMake quickly becomes unreadable, and I greatly prefer readability over compactness for the sake of compactness. Newlines are cheap :)

My biggest gripe about gersemi's formatting is that when it splits lines, it moves the first args to a new line, eg.

message(STATUS
  "Line one"
  "Line two"
)

becomes

message(
  STATUS
  "Line one"
  "Line two"
)

I do greatly prefer the first example, but I'm willing to concede that to avoid having to think about formatting going forward 🙂 This particular refactoring is the main contributor to the increase in size.

Overall, this PR adds ~2000 LOCs. Our repo has >20,000 lines of cmake total, so it's more like a 10% increase instead of 50% taken as a whole.

[miscco]

I will gladly take any automatic formatting over me hitting whitespaces

[bernhardmgruber]

Are there any options to keep the code more dense?

Dense CMake quickly becomes unreadable, and I greatly prefer readability over compactness for the sake of compactness. Newlines are cheap :)

Compactness up to some degree does strongly correlate with readability for me. But I guess this is a personal preference.

I'm willing to concede that to avoid having to think about formatting going forward 🙂

I agree!

[bernhardmgruber]

Overall, this PR adds ~2000 LOCs. Our repo has >20,000 lines of cmake total, so it's more like a 10% increase instead of 50% taken as a whole.

Yeah, that's a better reasoning. Still, if we go with 120, there is no increase :)

[alliepiper]

The issue with CMake is that there is a lot of structure within those function arguments, have having them broken out makes that structure more apparent and obvious -- this is the readability gain that we get here. Having all of the args squeezed into a single line loses that structure.

Maybe it's because I've spent hundreds or thousands of hours reading and writing CMake at this point, but I "just know" what eg. target_link_libraries or set_target_properties "looks like" when it's properly formatted. I can grok it at a glance if it's split out and formatted, and know exactly what it's doing with very little cognitive work. I can spot bugs and issues much easier in code where the internal structure of a call is shown through its formatting. The keywords and options are obvious, the lists of libraries / options are laid out in a row and easy to inspect...it's overall very easy and simple to read. It's delightful -- or at least as close as CMake gets to it 😉

If all of the keywords, options, and values are compressed into a single line, it takes much more cognitive effort to read through them, mentally parse them, group them, find what I'm looking for, catch bugs...each line, each token must be inspected one-by-one, rather being able to just skim / glance, and subtle bugs like quoting errors get lost in the soup. It's a lot more work to actually read and understand long, dense lines of CMake.

For these reasons I prefer the shorter, less dense lines of CMake. I'll also point out that I'm the one doing at least 98% of the CMake work for CCCL, so I'd like to ask that my opinions and subjective takes are allowed to carry a little more weight here 🙂

---

That said, there are some expansions I don't like and feel are unnecessary -- for instance function(...) / macro(...) definitions and calls to cmake_parse_arguments(). These could all go on a single line with no loss of readability, but gersemi currently splits all function calls that have more than 4 arguments in a group. I've asked for the ability to customize this per-command (BlankSpruce/gersemi#78), and the maintainer seems receptive and is considering it.

If they decide that's worth implementing and maintaining, we'll have much more control over when expansion vs inlining occurs on a per-command basis. This will let me set up gersemi to expand the commands that are useful to have expanded, but inline those that we don't really care about (message, function, macro, etc). At this point we can revisit the line-length settings, once we're able to ensure that the commands that should be expanded for readability are never inlined.

Sound like a good compromise for now?

[github-actions]

🥳 CI Workflow Results

🟩 Finished in 1h 31m: Pass: 100%/263 | Total: 2d 03h | Max: 1h 04m | Hits: 99%/384652

See results here.