doc: cmake: add cmake style guidelines

[nashif]

Add cmake style guidelines.

Signed-off-by: Anas Nashif [email protected]

[nordicjm]

Looks OK minus nit. in examples

[nordicjm]

these use 4 space indent

[tejlmand]

it still uses 4 space indent.

[tejlmand]

Perhaps: Use Uppercase for Cache Variables or variables shared across CMake files

as we do have variables that are shared / re-used throughout the CMake tree but are not cache variables.

[tejlmand]

Do you mean function arguments ?
You cannot have two CMake commands on a single line.

Also the example code block has two args on same line my_target and PRIVATE, which I think in this case is perfectly valid, but as PRIVATE technically is independent flag, then it becomes a bit unclear when this is acceptable, and when it should be avoided.

I think I know your intentions, and I agree with them, but current sentence is imprecise.

Sorry for not having a better suggestion atm.

[nashif]

hmm, maybe make this about files instead of commands, so this becomes clearte, i.e. One file per line

[tejlmand]

it still uses 4 space indent.

[tejlmand]

this uses four space indent.

Btw. do we want just the indent or alignment ?
I'm fine either way, but prefer consistency.

And should function calls spanning multiple lines wrap first arg also, that is if we only indent and not align the args.

A)

target_sources(my_target PRIVATE
  src/file1.cpp
  src/file2.cpp
)

A.a)

target_sources(
  my_target PRIVATE
  src/file1.cpp
  src/file2.cpp
)

B)

target_sources(my_target PRIVATE
               src/file1.cpp
               src/file2.cpp
)

[tejlmand]

this uses 4 space indent.

[tejlmand]

A good start 👍

[rettichschnidi]

Bit late to the party, but has https://github.com/BlankSpruce/gersemi/ been considered to be used instead of putting formatting details (use 2 spaces, no space after if, etc.) into a textual guideline?

[pdgendt]

Bit late to the party, but has BlankSpruce/gersemi been considered to be used instead of putting formatting details (use 2 spaces, no space after if, etc.) into a textual guideline?

Only attempt of CMake formatting was #82839, I think.

[tejlmand]

but has https://github.com/BlankSpruce/gersemi/ been considered to be used instead of putting formatting details (use 2 spaces, no space after if, etc.) into a textual guideline?

not sure if this specific formatter has been tried.
I tried various other formatters in the past with no good results, and @nordicjm has recently tried a lot of other formatters / linters with #82839 as the most promising one.

As a reference, I can also point to: https://discourse.cmake.org/t/cmake-linter/8391 from June 2023 which contains a reply from Craig Scott.

[buildSystemPerson]
CMake linter?
Does anyone have any recommendations for a CMake linter?

[Craig Scott]
I realise this is controversial, but my response at the moment is, frankly, don’t use one. In all cases where I’ve seen them used in any meaningfully complicated project, it gives a worse result than manual formatting.

...

So atm I think the best we can do is to have CMake format recommendations in writing.