From 980bee1315ac6789e41e1c286cc190b56a361efa Mon Sep 17 00:00:00 2001 From: "Mollenkopf, Fabian (RDSS)" Date: Mon, 3 Feb 2025 16:12:31 +0100 Subject: [PATCH] docs: update variant documentation --- .readthedocs.yml | 2 +- docs/getting_started/hello_world.rst | 10 + docs/getting_started/start_new_component.rst | 2 + docs/getting_started/start_new_variant.rst | 191 ++++++++++++++++++- docs/reference/macros.rst | 1 + 5 files changed, 204 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index b93b70b..4f16ade 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -12,7 +12,7 @@ build: jobs: post_create_environment: # Install poetry - - python -m pip install poetry + - python -m pip install poetry~=1.8 post_install: # Install dependencies, reusing RTD virtualenv - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install diff --git a/docs/getting_started/hello_world.rst b/docs/getting_started/hello_world.rst index 600c7ef..5526913 100644 --- a/docs/getting_started/hello_world.rst +++ b/docs/getting_started/hello_world.rst @@ -1,3 +1,5 @@ +.. _hello_world: + Tutorial: "Hello World" ======================= @@ -264,12 +266,15 @@ Write the following line in the ``variants/lang/de/parts.cmake`` file: spl_add_component(src/main) +.. _make_main_component_configurable: + Make the ``main`` Component Configurable ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We now need to make the ``main`` component configurable and define configurations for the two variants ``variants/lang/en`` and ``variants/lang/de``. To make the ``main`` component configurable, we need to create a `KConfig `_ model file in the ``src/main/`` directory: +Please note that this file has no specific file ending. It is simply called ``KConfig``. .. code-block:: KConfig :linenos: @@ -345,6 +350,11 @@ Add the following code to the ``src/main/src/main.c`` file: return 0; } +In order to properly handle the ``kconfiglib`` while generating and building, we also have to install SPL Core's Python package: + +.. code-block:: powershell + + pip install spl-core To generate the build files including ``autoconf.h`` for variant ``lang/de`` execute: diff --git a/docs/getting_started/start_new_component.rst b/docs/getting_started/start_new_component.rst index 7ac4521..0a82e1c 100644 --- a/docs/getting_started/start_new_component.rst +++ b/docs/getting_started/start_new_component.rst @@ -1,3 +1,5 @@ +.. _start_new_component: + How to Start Working on a :ref:`Component ` ############################################################### diff --git a/docs/getting_started/start_new_variant.rst b/docs/getting_started/start_new_variant.rst index 4d8eb54..c0a22f6 100644 --- a/docs/getting_started/start_new_variant.rst +++ b/docs/getting_started/start_new_variant.rst @@ -1,4 +1,193 @@ How to Start Working on a :ref:`Variant ` ########################################################### -TODO: write this section +In this guide, we will show you how to configure a new variant of your SPL. +We will cover the most common use cases for variant configuration, including feature selection, component inclusion, and build customization. +Some of these steps are also explained in the :ref:`"Hello World" Tutorial `. +However, this guide will provide a more detailed explanation of the variant specific configuration. + +.. attention:: + + As a precondition to this guide, you should have a project with at least one component set up and configured. + If you haven't done this yet, please refer to the guide on how to :ref:`start working on a component `. + +Variant directory structure +*************************** + +Inside your project root create a new directory for your variant. The name of this directory should be the name of the variant. +This will result in the following exemplary structure: + +.. code-block:: + + + └── variants + ├── var1 + │ + ├── var2 + │ + └── ... + +Select your components - ``parts.cmake`` +**************************************** + +The ``parts.cmake`` file contains the list of components which are part of your variant. +You have to manually create this file inside the variant directory: + +.. code-block:: + :emphasize-lines: 4 + + + └── variants + └── var1 + ├── parts.cmake + └── ... + +Add the following lines to the ``parts.cmake`` file to include the components you want to have as a part of your variant: + +.. code-block:: cmake + + spl_add_component(src/comp1) + spl_add_component(src/comp2) + +This :ref:`SPL Core specific macro ` is responsible for automatically including the components during the build process. + +At last you have to include ``parts.cmake`` in the ``CMakeLists.txt`` file of your project root. +You can achieve this by adding the following line to the ``CMakeLists.txt`` file after the inclusion of ``spl.cmake``: + +.. code-block:: cmake + :emphasize-lines: 11 + + # Fetch and make spl-core available + FetchContent_Declare( + spl-core + GIT_REPOSITORY https://github.com/avengineers/spl-core.git + GIT_TAG develop + ) + FetchContent_MakeAvailable(spl-core) + include(${spl-core_SOURCE_DIR}/cmake/spl.cmake) + + # Include the variant specific parts + include(${CMAKE_SOURCE_DIR}/variants/${VARIANT}/parts.cmake) + +Select your features - ``KConfig`` and ``config.txt`` +***************************************************** + +Think of ``KConfig`` as a tool to define possible features, while ``config.txt`` reflects the actual selection of those. +For more details, see the `official Kconfig documentation `_. + +The ``config.txt`` file contains then a list of features which are part of your variant. This file is automatically created using ``KConfig``. +However, there are still some steps you have to take care of. + +Create a ``KConfig`` model file in the root of your project.: + +.. code-block:: none + :emphasize-lines: 6 + + + ├── variants + │ └── ... + ├── src + │ └── ... + ├── KConfig + └── ... + +Add the following lines to include the ``KConfig`` files of your components: + +.. code-block:: KConfig + + menu "Features" + source "src/comp1/KConfig" + source "src/comp2/KConfig" + ... + endmenu + +Use ``KConfig``'s graphical user interface to create the corresponding ``config.txt`` file for your variant. +You can start it by running the following command: + +.. code-block:: powershell + + guiconfig + +See the :ref:`corresponding section from the "Hello World" tutorial ` to see how to install it and how to create the ``config.txt`` file. + +The generated ``config.txt`` now holds all the features you selected for your variant. Please note that this file is not meant to be edited manually. + +Additional CMake configurations - ``config.cmake`` +************************************************** + +In addition, for optional variant specific configurations like target architecture and toolchain, you can create a ``config.cmake`` file inside your variant directory: + +.. code-block:: none + :emphasize-lines: 6 + + + └── variants + └── var1 + ├── parts.cmake + ├── config.txt + ├── config.cmake + └── ... + +You have to include this file in the ``CMakeLists.txt`` file of your project root. +You can achieve this by adding the following lines to the ``CMakeLists.txt`` file before the ``project()`` macro is called for the first time: + +.. code-block:: cmake + :emphasize-lines: 2 + + # Include variant specific configurations + include(${CMAKE_SOURCE_DIR}/variants/${VARIANT}/config.cmake) + + if(BUILD_KIT STREQUAL prod) + project(${VARIANT} C ASM) + else() + # C++ project due to GTest usage + project(${VARIANT} C ASM CXX) + endif() + +Inside the ``config.cmake`` file you can set a bunch of different options using official CMake syntax. +Refer to the `official CMake documentation `_ for more information. +Here is a selection of some examples: + +- Build-kit and -type specific settings: + +.. code-block:: cmake + + if(BUILD_KIT STREQUAL prod) + if(CMAKE_BUILD_TYPE STREQUAL "Debug") + message(STATUS "Configuring Debug build") + endif() + endif() + +- Variant specific settings: + +.. code-block:: cmake + + set(VARIANT_C_FLAGS ${CCFLAGS}) + set(VARIANT_LINKER_FILE ${LDFILE}) + set(VARIANT_LINK_FLAGS ${LDFLAGS}) + +- CMake settings: + +.. code-block:: cmake + + set(CMAKE_C_FLAGS_DEBUG "-O0 -g") + set(CMAKE_C_FLAGS_RELEASE "-O3") + set(CMAKE_C_FLAGS ${VARIANT_C_FLAGS}) + +- Link options: + +.. code-block:: cmake + + add_link_options(-mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard -Wl,-Map=${BUILD_OUT_PATH}/${PROJECT_NAME}.map -T${VARIANT_LINKER_FILE}) + +- CMake toolchain file: + +.. code-block:: cmake + + set(CMAKE_TOOLCHAIN_FILE ${CMAKE_SOURCE_DIR}/tools/some_compiler/toolchain.cmake) + +.. note:: + + This ``toolchain.cmake`` file is generally used to set compiler specific options and flags using CMake syntax. + Having a dedicated toolchain file allows for consistent and reproducible builds across different environments and simplifies the configuration process by centralizing compiler and linker settings. + While each compiler should have its own toolchain file, you can easily configure your different variants to use different compilers by simply setting the corresponding ``toolchain.cmake`` file. diff --git a/docs/reference/macros.rst b/docs/reference/macros.rst index 3e20f40..4535887 100644 --- a/docs/reference/macros.rst +++ b/docs/reference/macros.rst @@ -3,6 +3,7 @@ CMake Macros ============ +.. _cmake-macro-spl-add-component: spl_add_component -----------------