docs: update variant documentation

docs/getting_started/hello_world.rst

@@ -264,12 +264,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 +348,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_variant.rst

@@ -1,4 +1,189 @@
 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 software project.
+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 processes.
+
+.. 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 a new 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
+        └── my
+            ├── 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
+        └── my
+            └── 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 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:
+
+.. code-block:: cmake
+
+    ...
+    # Include the variant specific parts
+    include(${CMAKE_SOURCE_DIR}/variants/${VARIANT}/parts.cmake)
+    ...
+
+Select your features - ``KConfig`` and ``config.txt``
+*****************************************************
+
+The ``config.txt`` file contains a list of features which are part of your variant. This file is automatically created with ``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: 5
+
+    <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.
+See the :ref:`corresponding section <make_main_component_configurable>` from the "Hello World" tutorial to see how it is done.
+
+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.
+
+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>`_.
+
+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
+        └── my
+            └── 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:
+
+.. code-block:: cmake
+
+    ...
+    # Include variant specific configurations
+    include(${CMAKE_SOURCE_DIR}/variants/${VARIANT}/config.cmake)
+    ...
+
+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")
+            set(BUILD_OUT_PATH build/default_Debug)
+            ...
+        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.