search

zephyrproject-rtos / zephyr

Primary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.
https://docs.zephyrproject.org
Apache License 2.0
10.34k stars 6.33k forks source link

CMake build architecture documentation #9947

Open tejlmand opened 5 years ago

tejlmand commented 5 years ago

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:

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

marc-hb commented 5 years ago

This is what the above commit produces: sphinx-moderncmakedomain-demo

marc-hb commented 5 years ago

@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 commented 5 years ago

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 commented 4 years ago

I believe this is resolved by https://github.com/zephyrproject-rtos/zephyr/pull/20324 , if not I'd like to know more about what needs to be documented.

marc-hb commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 6 months ago

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 commented 6 months ago

This is still valid and valuable IMHO