CMake build architecture documentation

[tejlmand]

Currently the CMake documentation
https://docs.zephyrproject.org/latest/application/application.html#cmake-details
targets users starting out with the creation of the own applications.

The CMake architecture, especially on how source is organized into libraries should be documented so it is clear and structured to zephyr contributors.

Areas of importance:

• Kernel
• arch
• drivers
• subsystems
  • Bluetooth
  • Network
  • etc.
• Others

Also, important internals of the build system should be made with all important CMake variables, like:

• ZEPHYR_<MODULE_NAME> related variables
• ROOT variables
• BOARD variable
• BOARD_REVISION variable

[marc-hb]

This is what the above commit produces:

[marc-hb]

@SebastianBoe , @tejlmand, @mped-oticon, @carlescufi is this issue #9947 the right place to discuss this sphinx-moderncmakedomain prototype and proposal? I have a number of questions (see latest commit) and I'd like to get the discussion started but not in the wrong place. Thx!
https://lists.zephyrproject.org/g/devel/topic/29744819

[SebastianBoe]

Hi, very sorry for the late reply.

A dedicated PR with an RFC or DNM tag seems to me to be the best place to discuss the prototype.

[SebastianBoe]

I believe this is resolved by #20324 , if not I'd like to know more about what needs to be documented.

[marc-hb]

FWIW PoC/draft #13805 demoed how sphinx can be used to extract documentation straight from the CMake code. #20324 seems much higher level (and more important!).

[tejlmand]

Re-opened, as #20324 only describes the high level architecture (which is also important).

But it does not describe zephyr_library_* functions and other extension commands.
And when to use zephyr_sources() or zephyr_library() + zephyr_library_sources, and so on.

What we need is something similar to the proposal in #13805

The problem today, is that people must read: https://github.com/zephyrproject-rtos/zephyr/blob/master/cmake/extensions.cmake
in order to understand Zephyr CMake extension, which is not easy for new comers.

Also, having them documented only in a cmake file, means they will not show up when people search.
Compared to raw CMake, where a lot of good online documentation is available, as well as Q/A regarding CMake on stack overflow.
(Solving #8439 could remove or minimize the need for maintaining Zephyr CMake documentation)

@marc-hb should we reopen 13805 and continue work ?

[marc-hb]

@marc-hb should we reopen 13805 and continue work ?

@tejlmand why not, however I won't be able to personally resume work on this in the short or medium term.

[zephyrbot]

Hi @tejlmand,

This issue, marked as an Enhancement, was opened a while ago and did not get any traction. Please confirm the issue is correctly assigned and re-assign it otherwise.

Please take a moment to review if the issue is still relevant to the project. If it is, please provide feedback and direction on how to move forward. If it is not, has already been addressed, is a duplicate, or is no longer relevant, please close it with a short comment explaining the reason.

Thanks!

[marc-hb]

This is still valid and valuable IMHO