From 6c684e4b662e42c44ca061ad0ca1e92fa9706701 Mon Sep 17 00:00:00 2001 From: Yanfeng Liu Date: Wed, 17 Jul 2024 13:05:01 +0800 Subject: [PATCH] docs/cmake: add out-of-tree usage This adds out-of-tree usage guide of CMake for FLAT, PROTECTED and KERNEL configs so that more kernel developers can enjoy cmake for their daily work. Signed-off-by: Yanfeng Liu --- Documentation/quickstart/compiling_cmake.rst | 71 ++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/Documentation/quickstart/compiling_cmake.rst b/Documentation/quickstart/compiling_cmake.rst index 86259aa6b1d5d..55630f9fc72db 100644 --- a/Documentation/quickstart/compiling_cmake.rst +++ b/Documentation/quickstart/compiling_cmake.rst @@ -57,3 +57,74 @@ To clean the build, you can do: .. code-block:: console $ cmake --build build -t clean + +Out-of-tree building +==================== + +Key benefit of CMake is the out-of-tree building, which allows one to have different build folders for different configs, very proper if one need check multiple configs for the same codebase. Out-of-tree means above ``build`` folders can be out of Nuttx source tree. + +Suppose ``$NUTTX_DIR`` is the nuttx source tree, we can use temporary folder for a particular target config as shown below. + + .. code-block:: console + + $ echo $NUTTX_DIR + /home/user/Projects/Nuttx/nuttx + $ mkdir -p ~/tmp/rv32/nsh + $ cd ~/tmp/rv32/nsh + # Make sure a proper toolchain is in your $PATH + $ riscv64-unknown-elf-gcc -v + $ cmake $NUTTX_DIR -DBOARD_CONFIG=rv-virt:nsh -GNinja + -- Initializing NuttX + -- Board: rv-virt + -- Config: nsh + -- Appdir: /home/yf/Projects/Nuttx/apps + -- The C compiler identification is GNU 10.2.0 + -- The CXX compiler identification is GNU 10.2.0 + -- The ASM compiler identification is GNU + -- Found assembler: /usr/bin/riscv64-unknown-elf-gcc + -- Configuring done + -- Generating done + -- Build files have been written to: /home/yf/tmp/rv32/nsh + $ ninja + $ size nuttx + text data bss dec hex filename + 167411 365 11568 179344 2bc90 nuttx + +This approach works for FLAT configs now and PROTECTED configs soon if needed CMake scripts are available already. + +Building KERNEL configs +======================= + +We can use CMake to build the kernel image for KERNEL configs now, assuming apps ROMFS is prepared using the makefile system. If the development focus is kernel side and apps don't change often, then CMake can help us achieve out-of-tree build if your device's CMake scripts are ready. Let's take ``canm230`` device as an example: + + .. code-block:: console + + $ echo $NUTTX_DIR + /home/user/Projects/Nuttx/nuttx + $ mkdir -p ~/tmp/k230/nsbi + # copy the romfs_boot.c to build folder + $ cp romfs_boot.c ~/tmp/k230/nsbi + $ cd ~/tmp/k230/nsbi + $ ls -l + total 976 + -rw-rw-r-- 1 yf yf 997843 Jul 15 06:23 romfs_boot.c + $ cmake $NUTTX_DIR -DBOARD_CONFIG=canmv230:nsbi -GNinja + -- Initializing NuttX + -- Board: canmv230 + -- Config: nsbi + -- Appdir: /home/yf/Projects/Nuttx/apps + -- The C compiler identification is GNU 10.2.0 + -- The CXX compiler identification is GNU 10.2.0 + -- The ASM compiler identification is GNU + -- Found assembler: /usr/bin/riscv64-unknown-elf-gcc + -- Configuring done + -- Generating done + -- Build files have been written to: /home/yf/tmp/k230/nsbi + $ ninja + $ size nuttx + text data bss dec hex filename + 281671 609 37496 319776 4e120 nuttx + +Note that for QEMU targets, we can directly use the apps binary on host folder via ``hostfs`` in QEMU. + +So even apps side CMake support is not ready, we still can enjoy CMake for kernel build with KERNEL configs.