Difference between the ZEPHYR_BASE and PROJECT_SOURCE_DIR CMake variables is unclear

[ulfalizer]

To me anyway.

cmake/kconfig.cmake references kconfig.py via ${PROJECT_SOURCE_DIR}/scripts/kconfig/kconfig.py, while you have e.g. include(${ZEPHYR_BASE}/boards/common/pyocd.board.cmake) in other places.

Looking at https://github.com/zephyrproject-rtos/zephyr/blob/master/cmake/app/boilerplate.cmake#L75, they seem to be synonyms.

@SebastianBoe pointed out that PROJECT_SOURCE_DIR is a standard CMake variable, so maybe it's added as a synonym for ZEPHYR_BASE for people who are familiar with CMake. Would be nice to have it documented if that's it.

[ulfalizer]

CC @carlescufi

[SebastianBoe]

Not sure how to document this. But this is the situation:

PROJECT_SOURCE_DIR is a CMake variable with documented behaviour and should always reflect what CMake documents about it.

CMake's 'project' concept has proven to not be very useful for Zephyr due in part to how Zephyr is organized and in part to it not fitting well with cross compilation[citation needed].

CMake therefore tries to rely as little as possible on project() and it's associated variables, e.g. PROJECT_SOURCE_DIR.

It is recommended to always use ZEPHYR_BASE instead of PROJECT_SOURCE_DIR when trying to reference ENV${ZEPHYR_BASE} because users are expected to already know what ZEPHYR_BASE is, but are not expected to understand what PROJECT_SOURCE_DIR is. Plus it's shorter.

Therefore to resolve this issue we should search-replace PROJECT_SOURCE_DIR with ZEPHYR_BASE and add a comment to PROJECT_SOURCE_DIR explaining the above. Also, perhaps look into if we should be setting it differently (or not be setting it manually at all).