How to compile the zephyr example-application as a freestanding application?

The Zephyr documentation recommends to use the example-application as a starting point. The given approach using git is wrong, however. According to the example's readme, it needs to be initialized using west:

west init -m https://github.com/zephyrproject-rtos/example-application --mr main my-workspace

But this means that the workspace will be a T2 topology, i.e. the entire Zephyr source code will live inside the app repository. This means that if I develop multiple apps this way, I will have the entire Zephyr source code on my disk multiple times.

Therefore I would like to implement this app as a freestanding app, i.e. the Zephyr sourcecode should be located in an entirely different directory.

Simply running

west build -b nucleo_wl55jc . --pristine

inside the cloned example-application results in

usage: west [-h] [-z ZEPHYR_BASE] [-v] [-V] <command> ...
west: unknown command "build"; do you need to run this inside a workspace?

Solution

After quite some try & error, I found it out myself.

The main issue is building the application without the T2 topology, i.e. with the application not being the root directory. The application will still be the "root" of the build process, but it needs to depend on the other components in the example-application repository (particularly, drivers, dts files & bindings, board definitions) which should be built as well.

To achieve this, everything but the app needs to go into its own directory which is not a parent of the app directory. Therefore, create a directory (e.g. called common but name doesn't matter) inside the example-application and move everything into it except the app directory:

mkdir common
shopt -s extglob 
mv ./!(.git|app|common) common

As the common folder already contains a zephyr/module.yml file, it is already a proper Zephyr module.

Edit the app/CMakeLists.txt and add the dependency to this module by using EXTRA_ZEPHYR_MODULES:

cmake_minimum_required(VERSION 3.13.1)

# This has to go before find_package!
list(APPEND EXTRA_ZEPHYR_MODULES 
  ${CMAKE_CURRENT_SOURCE_DIR}/../common
)

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})

If the example-application is somewhere within the Zephyr source tree, it can be built directly using west. If not, the ZEPHYR_BASE environment variable needs to be set before:

ZEPHYR_BASE="/home/me/zephyrproject/zephyr"
west build -b custom_plank app --pristine