# Feature request: Universal enforcement of CMake script formatting
**URL:** https://discourse.cmake.org/t/feature-request-universal-enforcement-of-cmake-script-formatting/4852
**Category:** Development
**Created:** [January 14, 2022, 10:33am UTC](https://discourse.cmake.org/t/feature-request-universal-enforcement-of-cmake-script-formatting/4852 "2022-01-14T10:33:46Z")
**Posts on this page:** 4
**Page:** 1
### Author:  [@tom](https://discourse.cmake.org/u/tom)
#### Post date: [January 14, 2022, 10:33am UTC](https://discourse.cmake.org/t/feature-request-universal-enforcement-of-cmake-script-formatting/4852/1 "2022-01-14T10:33:46Z")
Hi,
I think official enforcement of “correct” CMake code formatting would make reading and writing CMake code significantly faster and easier. I’d like to see a tool from Kitware that ships with CMake and can be run on a CMake file to make it comply with Kitware’s official style guidelines for CMake code format. I’d even go so far as to have CMake complain about formatting at configuration-time.
Motivation:
- I wish I had auto-formatting tools when writing CMake code,
- I _really_ wish other developers in my company had auto-formatting tools when writing CMake code,
- I think arguing about CMake formatting guidelines is a form of [bikeshedding](https://en.wikipedia.org/wiki/Law_of_triviality) - I’d rather not think about it and blindly follow the official guidelines,
- If you google “CMake coding style”, the first three results are from KDE, ROS, and Jetbrains. I bet they wish they could stop publishing guidelines and just say “use the official tool”,
- In [this](https://www.youtube.com/watch?v=uZI_Qla4pNA&t=1907s) talk, Chandler Carruth (Google DevOps, C++ standards committee, all-round smart guy) says “[clang-format, a C++ auto-formatting tool, is] the single largest improvement in your productivity as a developer”. I think the same might apply to CMake.
Caveats:
- If Kitware choose different standardisations to existing codebases, they might be upset. If there’s an auto-formatting tool then maybe they won’t be very upset,
- I’m aware of tools like [this](https://marketplace.visualstudio.com/items?itemName=cheshirekow.cmake-format), which are a great start, but I’d like to see greater adoption and more universality,
- I’m not a CMake developer, nor have I ever written any lexing/parsing code, so I have no idea how much effort this entails.
Thanks,
Tom
---
### Author:  [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)
#### Post date: [January 16, 2022, 6:12pm UTC](https://discourse.cmake.org/t/feature-request-universal-enforcement-of-cmake-script-formatting/4852/2 "2022-01-16T18:12:39Z")
CMake’s…loose syntax makes this very hard. Knowing whether a function argument is a keyword or not, how many arguments it takes after that, etc. is _really_ hard. Not to mention what kind of effects quoting or variable expansions have at various places, etc. “Standard” commands could probably have some standard syntax formatting since the argument sets are “known”, but user-defined commands can have all kinds of logic applied to them.
FWIW, my rules are basically along the lines of:
- 2 space indent
- spaces after “control flow” commands (`if`, `else`, `function`, `while`, `return`, `continue`, `end*`, etc.), otherwise no space
- quote all variable expansions except:
- when `if` cares
- when it is a list of arguments
- for argument blocks, vertical alignment is good (whether hanging indents or not)
Not to discourage anyone else from trying, but figuring out how to apply these rules to arbitrary code is not something I think is a good use of _my_ time at least.
---
### Author:  [@benthevining](https://discourse.cmake.org/u/benthevining)
#### Post date: [January 18, 2022, 6:48am UTC](https://discourse.cmake.org/t/feature-request-universal-enforcement-of-cmake-script-formatting/4852/3 "2022-01-18T06:48:42Z")
One thing on my wishlist for CMake is a documentation generation tool for CMake scripts and modules – perhaps, down the line, these two things could be integrated? It stands to reason that if the developer is telling the docs tool, “for this function, these are the options, these are the single value args, these are the multi value args”, then a lexer/linter/formatter tool could use that information to provide hints or reformatting at each call site of said function.
It may not even require much extra effort from the developer, since ~90% of the time I see `cmake_parse_arguments` used it’s in pretty much exactly this form:
```cmake
set (options "")
set (oneValueArgs "")
set (multiValueArgs "")
cmake_parse_arguments (PREFIX "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
```
I could even see supporting in-code documenting of functions arguments with something like this:
```cmake
set (options
OPTION_1 # doc string for option 1
OPTION_2 # doc string for option 2
)
set (oneValueArgs
ARG_1 # doc string for arg 1
ARG_2 # doc string for arg 2
)
```
---
### Author:  [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)
#### Post date: [January 18, 2022, 12:24pm UTC](https://discourse.cmake.org/t/feature-request-universal-enforcement-of-cmake-script-formatting/4852/4 "2022-01-18T12:24:09Z")
> [@benthevining](#):
>
> then a lexer/linter/formatter tool could use that information to provide hints or reformatting at each call site of said function
Just for the record, formatters usually don’t need to follow include paths to format the code. Since CMake files are rarely standalone, you also need to see what is included anywhere before the file in question is executed to peruse for such API docstrings for formatting help. Since `include()` usually relies on runtime manipulation of `CMAKE_MODULE_PATH`, a full CMake interpreter needs to be run to be a “formatter” (though a lint tool which does deeper static analysis would be able to do this).
Another case that came to mind are APIs that wrap another. They “skim off” a set of arguments and then pass the rest off to some other API. Getting such information is difficult. There’s also the “multiple arguments that take multiple values” where each instance of the keyword argument needs handled individually that `cmake_parse_arguments` just doesn’t handle today (IME, this is far rarer than the “wrapper” API).