docs: update variant documentation

.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

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 <https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html#kconfig-syntax>`_ 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:
 

docs/getting_started/start_new_component.rst

@@ -1,3 +1,5 @@
+.. _start_new_component:
+
 How to Start Working on a :ref:`Component <glossary_component>`
 ###############################################################
 

docs/getting_started/start_new_variant.rst

@@ -1,4 +1,193 @@
 How to Start Working on a :ref:`Variant <glossary_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 <hello_world>`.
+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 <start_new_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::
+
+    <project root>
+    └── 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
+
+    <project root>
+    └── 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 <cmake-macro-spl-add-component>` 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 <https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html>`_.
+
+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
+
+    <project root>
+    ├── 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 <make_main_component_configurable>` 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
+
+    <project root>
+    └── 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 <https://cmake.org/cmake/help/latest/index.html>`_ 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.

docs/reference/macros.rst

@@ -3,6 +3,7 @@
 CMake Macros
 ============
 
+.. _cmake-macro-spl-add-component:
 
 spl_add_component
 -----------------