make IDEs aware of the headers

[Andrey Butirsky]

Hi all,

let me introduce my finding we probably want for all KDE's CMake-based 
projects eventually.

The idea is, wherever we add a source files to a project, we should also 
add a headers alongside:

|add_library(my_lib [STATIC|SHARED|MODULE] [source.cpp source.h ...]) 
add_executable(my_exe [source.cpp source.h]) target_sources(my_target 
<INTERFACE|PUBLIC|PRIVATE> [source.cpp source.h])|

That has zero impact for building the project, as the headers do not get 
compiled directly,
but declaring headers in a such way helps IDEs (Qt Creator, etc.) be 
aware of them and work with them properly.

For now, KWin MR 
<https://invent.kde.org/plasma/kwin/-/merge_requests/3400> exists which 
adds the most essential headers, but even to fully cover KWin alone that 
would probably require some sort of automation as it contains ~138 
CMakeLists.txt files.

Until that automation method is not found, I hope it's OK to add the 
headers manually or semi-automated 
<https://invent.kde.org/plasma/kwin/-/merge_requests/3400#note_593030>.


Hereby is the MR message with all the details:

> Nowadays, it's generally recommended to add headers alongside with 
> sources in CMake:
>
>>     note that .h header files were specified as sources too, not just
>>     the .cpp implementation files. *Headers listed as sources don’t
>>     get compiled directly on their own, but the effect of adding them
>>     is for the benefit of IDE generators* like Visual Studio, Xcode,
>>     Qt Creator, etc. This causes those headers to be listed in the
>>     project’s file list within the IDE, even if no source file refers
>>     to it via #include. This can make those headers easier to find
>>     during development and potentially aid things like refactoring
>>     functionality, etc.
>>
> https://crascit.com/2016/01/31/enhanced-source-file-handling-with-target_sources/ 
>
>
> Recent Qt Creator depends on it heavily:
>
>>         This means that the header files will get the same treatment
>>         as the source files.
>>
>>           * clang-tidy and clazy will be able to analyze them
>>           * The TODO plugin can find the TODOs in header files
>>           * The Test plugin can find the Google Tests defined in
>>             header files
>>
> https://www.qt.io/blog/qt-creator-6-cmake-update
> In my personal observations it should also help with source/header 
> jumps as it sometimes doesn't work reliably otherwise.
>
> Other IDEs should benefit too.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/plasma-devel/attachments/20230107/a43072d4/attachment-0001.htm>