docs: update variant documentation #170
Conversation
Test Results50 tests 50 ✅ 7m 18s ⏱️ Results for commit b9ca264. ♻️ This comment has been updated with latest results. |
LeMollinger
force-pushed
the
169-update-documentation-of-spl-core
branch
from
0aa4efa to
08d51b0
Compare
.readthedocs.yml
Outdated
There was a problem hiding this comment.
This is only for checking if a newer version of poetry is responsible for the failing readthedocs build. In the last failing build, poetry v 2.0.1 has been used. Our lock file is generated by poetry v 1.8.5.
There was a problem hiding this comment.
Please use >=1.8 to make sure we also get the latest 1.x updates.
There was a problem hiding this comment.
using this syntax will result in readthedocsbuild failing again. Instead, i used pip install poetry~=1.8
This will allow us to use all the 1.x versions of poetry, but not 2.x
| 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. |
There was a problem hiding this comment.
processes can be removed or?
| @@ -1,4 +1,172 @@ | |||
| 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. | |||
There was a problem hiding this comment.
I think it is better if we talk about SPLs and not about projects. We would like to switch focus from a project to a product.
|
|
||
| <project root> | ||
| └── variants | ||
| └── my |
There was a problem hiding this comment.
Use one one directory for the variant name. SPL-Core supports variants with one directory, e.g. variants/var1
There was a problem hiding this comment.
i got this from the "Hello World" Tutorial
| 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. |
There was a problem hiding this comment.
Add a reference to the spl_add_component macro documentation.
| .. code-block:: cmake | ||
|
|
||
| # Include the variant specific parts | ||
| include(${CMAKE_SOURCE_DIR}/variants/${VARIANT}/parts.cmake) |
There was a problem hiding this comment.
Mention that this file must be included after the spl_core cmake is included. In this way the spl macros are visible and the ${VARIANT} variable is defined.
| ... | ||
| endmenu | ||
|
|
||
| Use ``KConfig``'s graphical user interface to create the corresponding ``config.txt`` file for your variant. |
There was a problem hiding this comment.
How to start the KConfig GUI?
| 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``. |
There was a problem hiding this comment.
Explain somehow that the KConfig file describes the SPL feature model and that config.txt stores the specific selection of features for the variant.
There was a problem hiding this comment.
I've just read this explanation at the end of the section... maybe you move it at the top of the section.
| ├── config.cmake | ||
| └── ... | ||
|
|
||
| You have to include this file in the ``CMakeLists.txt`` file of your project root. |
There was a problem hiding this comment.
Because this file defines the toolchain and/or options, it must be included in the CMakeLists.txt before the project() macro is called.
| if(BUILD_KIT STREQUAL prod) | ||
| if(CMAKE_BUILD_TYPE STREQUAL "Debug") | ||
| message(STATUS "Configuring Debug build") | ||
| set(BUILD_OUT_PATH build/default_Debug) |
There was a problem hiding this comment.
I do not like that for a specific configuration the build output path is "special".
I would not have this as an example.
There was a problem hiding this comment.
would it be sufficient to remove the line about the special output path? Personally, i like to see that someone can configure build_kit specifics. I would leave then the "message(STATUS ....)" line inside.
| 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 |
There was a problem hiding this comment.
Maybe add an overview with the most common use cases for variant specific configuration:
- relevant components
- feature selection
- toolchain and options
- misc
LeMollinger
force-pushed
the
169-update-documentation-of-spl-core
branch
2 times, most recently
from
dc194f6 to
abff7d1
Compare
LeMollinger
force-pushed
the
169-update-documentation-of-spl-core
branch
from
abff7d1 to
b9ca264
Compare
LeMollinger
dismissed
cuinixam’s stale review
I adapted all the requested changes. Now, I just want to merge it.
No description provided.