@@ -237,7 +237,7 @@ all the commands.
devtool
quick reference.
-Three ``devtool`` subcommands provide entry-points into
+Four ``devtool`` subcommands provide entry-points into
development:
- *devtool add*: Assists in adding new software to be built.
@@ -245,6 +245,8 @@ development:
- *devtool modify*: Sets up an environment to enable you to modify
the source of an existing component.
+- *devtool ide*: Generates a configuration for an IDE.
+
- *devtool upgrade*: Updates an existing recipe so that you can
build it for an updated set of source files.
@@ -632,6 +634,99 @@ command:
proceed with your work. If you do use this command, realize that
the source tree is preserved.
+Use ``devtool ide`` to generate an configuration for the IDE
+------------------------------------------------------------
+
+``devtool ide`` automatically configures the IDE for cross-compiling and remote debugging.
+The IDE is configured to call for example cmake directly. This has several advantages.
+First of all it is much faster than using e.g. ``devtool build``. But it also allows to
+use the very good integration of build tools like cmake or gdb with VSCode directly.
+
+Two different use cases are supported:
+
+- Generate the IDE configuration for a workspace created by ``devtool modify``.
+
+- Generate the IDE configuration for using a cross-toolchain as provided by
+ ``bitbake meta-ide-support build-sysroots``.
+
+Assuming the development environment is set up correctly and a workspace has been created
+for the recipe using ``devtool modify recipe``, the following command can create the
+configuration for VSCode in the recipe workspace:
+
+ $ devtool ide recipe core-image-minimal --target root@192.168.7.2
+
+What this command does exactly depends on the recipe or the build tool used by the recipe.
+Currently, only CMake and Meson are supported natively.
+
+For a recipe which inherits cmake it does:
+
+- Prepare the SDK by calling bitbake core-image-minimal, gdb-cross, qemu-native...
+
+- Generate a cmake-preset with configures cmake to use exactly the same environent and
+ the same cmake-cache configuration as used by ``bitbake recipe``. The cmake-preset referres
+ to the per-recipe-sysroot of the recipe.
+
+ Currently Configure, Build and Test presets are supported. Test presets execute the test
+ binaries with Qemu.
+
+- Generates a helper script to handle the do_install with pseudo
+
+- Generates some helper scripts to start the gdbserver on the target device
+
+- Generates the ``.vscode`` folder containing the following files:
+
+ - c_ccp_properties.json: configure the code navigation
+
+ - extensions.json: Recommend the extensions which are used.
+
+ - launch.json: Provide a configuration for remote debugging with gdb-cross and gdbserver.
+ The debug-symbols are searched in the build-folder, the per-recipe-sysroot and the rootfs-dbg
+ folder which is provided by the image.
+
+ - settings.json: confgure the indexer to ignore the build folders
+
+ - tasks.json: Provide some helpers for running
+
+ - do_install and ``devtool deploy-target``
+
+ - start the gdbserver via ssh
+
+For a recipe which inherits meson a similar configuration is generated.
+Because there is nothing like a meson-preset a wrapper script for meson is generated.
+
+For some special recipes and use cases a per-recipe-sysroot based SDK is not suitable.
+Therefore devtool ide also supports setting up the shared sysroots environment and generating
+a IDE configurations referring to the shared sysroots. Recipes leading to a shared sysroot
+are for example meta-ide-support or shared-sysroots. Also passing none as a recipe name leads
+to a shared sysroot SDK.
+
+ $ devtool ide none core-image-minimal
+
+In case of a shared sysroot SDK the configuration which gets generated for VSCode exposes the
+cross-tool-chain as a cmake-kit. If a cmake project is loaded into VSCode the cross-toolchain
+can be selected for compiling.
+
+The default IDE is VSCode. Some hints about using VSCode:
+
+- To work with cmake press ``Ctrl + Shift + p``, type cmake.
+ This will show some possible commands like selecting a cmake preset, compiling or running ctest.
+ A cmake kit might be activated by ``Ctrl + Shift + p``, type cmake quick start,
+ if not preset file is in the wokspace.
+
+- To work with meson press ``Ctrl + Shift + p``, type meson.
+ This will show some possible commands like compiling or executing the unit tests.
+
+- For the deployment to the target device, just press ``Ctrl + Shift + p``, type task.
+ Select the install & deploy task.
+
+- For remote debugging, switch to the debugging view by pressing the play button with the bug on the left side.
+ This will provide a green play button with a drop-down list where a debug configuration can be selected.
+ After selecting one of the generated configurations, press the play button.
+
+Additionally ``--ide=none`` is supported.
+With the none IDE some generic configurations files like .gdbinit files and some helper scripts
+are generated.
+
Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software
-------------------------------------------------------------------------------------------------------
Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com> --- documentation/sdk-manual/extensible.rst | 97 ++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-)