Common typos | syntax confusions | misspelling CMake problems.

[ArtsiomCh]

Hi everyone. I'm planning to implement some syntax inspections (potentially with quick fixes), as well as some code completion rules. For doing that I need advice on what are most common typos | syntax confusions | misspelling CMake problems. Presently I have the next list to do:

• Report when Variable is set but never used (done in dev);
• Report Set command syntax/signature mismatch (in progress);
• Report if command condition syntax/signature mismatch (in progress);

I would highly appreciate any suggestions from people with a heavy hand on CMake scriptwriting experience. At least name please the command you've had problems the most and if possible give a short description of what parameter/argument causes the most confusion.

@csitarichie please have look and pass on for anyone you think can give valuable feedback. @purpleKarrot would really admire your help (Thanks for great talks!).

[csitarichie]

I will take a look sorry for the late answer, ...

One of the annoying things is the formatting in clion. It is not possible to set it properly for function call argument indenting.

In cmake normally function takes kind of [KEY Value] lists, as input, for example:

adst_add_component(
    TARGET adstlog_cxx
    SOURCE
        adstlog.cpp
    INTERFACE_HEADER
        adstlog.hpp
        p7_trace_wrapper.hpp
    DEPENDS
        P7
        fmt
        config_cxx
)

example above KEY = TARGET value = adstlog_cxx and KEY = INTERFACE_HEADER value = adstlog.hpp p7_trace_wrapper.hpp

Now the only way to use the formating features for cmake file in clion is to put the KEY and the values in new lines under each other starting at the same indent, like this:

adst_add_component(
    TARGET adstlog_cxx
    SOURCE
    adstlog.cpp
    INTERFACE_HEADER
    adstlog.hpp
    p7_trace_wrapper.hpp
    DEPENDS
    P7
    fmt
    config_cxx
)

this makes the code much less readable and more error prone. I really a fun of the nicely indented function call like the first code snippet. It would be nice if the plugin would be able to somehow allow to use such an auto-indentation possibility

[purpleKarrot]

For formatting, the trickiest command is install. IMO, the most readable formatting is:

install(TARGETS ${targets} EXPORT export_set
  ARCHIVE
    DESTINATION lib
    COMPONENT develop
  RUNTIME
    DESTINATION bin
    COMPONENT runtime
  )

This presents a whole bunch of special cases that derive from the each-token-on-its-line-and-indent-between-keys-approach.

[purpleKarrot]

I would welcome the following lint rules:

• :heavy_check_mark: Builtin commands are used in lowercase.

  ADD_LIBRARY(...) # Bad
  add_library(...) # Good

• :heavy_check_mark: Commands like ExternalProject_Add use mixed-case, as they are documented.

  externalproject_add(...) # Bad
  ExternalProject_Add(...) # Good

• :heavy_check_mark: Commands else, endif, endforeach, endwhile, endfunction, endmacro don't take arguments.

  endif(FOO STREQUAL BAR) # Bad
  endif() # Good

• option is used for boolean cache entries:

  set(FOO ON CACHE BOOLEAN "Some option") # Bad
  option(FOO "Some option" ON) # Good

• Encourage use of proper manipulation commands for string/list manipulation:

  set(FOO ${FOO} new_item) # Bad
  list(APPEND FOO new_item) # Good

• if-conditons are tricky. Make sure to to let variables be dereferenced automatically and put values in quotes. Also make sure the value is on the right side.

  if(${FOO} STREQUAL BAR) # Bad
  if(BAR STREQUAL ${FOO}) # Bad
  if(FOO STREQUAL "BAR") # Good

• Discourage the use of variables:

  # Bad
  set(target foo)
  set(sources foo.c bar.c)
  if(WIN32)
  list(APPEND sources win.c)
  endif()
  add_library(${target} ${sources})
  
  # Good
  add_library(foo)
  target_sources(foo PRIVATE foo.c bar.c)
  if(WIN32)
  target_sources(foo PRIVATE win.c)
  endif()

[csitarichie]

For formatting, the trickiest command is install. IMO, the most readable formatting is:

install(TARGETS ${targets} EXPORT export_set
  ARCHIVE
    DESTINATION lib
    COMPONENT develop
  RUNTIME
    DESTINATION bin
    COMPONENT runtime
  )

This presents a whole bunch of special cases that derive from the each-token-on-its-line-and-indent-between-keys-approach.

@purpleKarrot Hi Long time no see (we met a few times in c++ meetup in MUC ). Never the less your example is almost perfect the only case which is not shown above when the TOKEN takes a list of values like SOURCES for example. I'm writing each element of the list in a new line.

[ArtsiomCh]

@csitarichie @purpleKarrot Hi folks! It's been a while since you gave me that nice ideas above. As you can see some of them are implemented and some still in progress/postponed. Also many other features been implemented in CMake Plus plugin recently. Please have a look if you've missed it. And in respect of your contribution Santa :) willing to give free 1 year license for both of you, just write me in PM if you like one. In the present time I'm planning to implement code formatting. Looks like it's require a lot of work if doing it from scratch... :( At the same time I see there's nice cmake-format tool that seems to be widely used in industry (based on number of forks and stars given). I did play with it a little and I like it ability of customization and fine-tuning (and it defaults seems to be decent enough for most of cmake users). Shell I try to integrate that cmake-format tool into CLion/Idea instead of creating yet-another-formatter? I mean, does it looks mature and good enough for you personally (and for your colleagues) to use? @cheshirekow Would you mind please give any ideas about future of that cmake-format project? I.e. I see last commit was on May 13, 2021. Does that means the tool is "perfect" :) and no updates/improvements needed, or it's just abandoned :( and no further development should be expected? Anyway, Thanks a lot for such a great tool!

[ArtsiomCh]

Ok folks, integration with cmake-format done in CMake Plus 223.7.0 version. Generally any external formatter could be used that accept next command: <path_to_binary> <path_to_current_file> <parameters> and replace file text with resulting stdout(if exit code = 0).

[cheshirekow]

Would you mind please give any ideas about future of that cmake-format project? I.e. I see last commit was on May 13, 2021. Does that means the tool is "perfect" :) and no updates/improvements needed, or it's just abandoned :( and no further development should be expected?

It's not "perfect", but it functions well and the biggest outstanding issues have workarounds so it's in a relatively good place overall. I have a couple of releases in the queue for minor bug fixes and enhancements but I haven't gotten around to pushing them through. The pandemic has more or less destroyed my free time so I have had very little opportunity to do further work on it or even maintain the CI infra over the past couple of years... so I'll need to blow off the cobwebs when I do have a chance to knock those out.

Anyway, Thanks a lot for such a great tool!

I'm glad it was helpful to someone :).