Cover the new devtool ide plugin in the extensible sdk section.
Many thanks to Enguerrand de Ribaucourt for his re-view and
contributions.
Signed-off-by: Adrian Freihofer <adrian.freiho...@siemens.com>
---
documentation/sdk-manual/extensible.rst | 158 +++++++++++++++++++++++-
1 file changed, 157 insertions(+), 1 deletion(-)
diff --git a/documentation/sdk-manual/extensible.rst
b/documentation/sdk-manual/extensible.rst
index 355c6cb0e4a..361ca091fbf 100644
--- a/documentation/sdk-manual/extensible.rst
+++ b/documentation/sdk-manual/extensible.rst
@@ -230,13 +230,15 @@ all the commands.
See the ":doc:`/ref-manual/devtool-reference`"
section in the Yocto Project Reference Manual.
-Three ``devtool`` subcommands provide entry-points into development:
+Four ``devtool`` subcommands provide entry-points into development:
- *devtool add*: Assists in adding new software to be built.
- *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.
@@ -614,6 +616,160 @@ command:
decide you do not want to proceed with your work. If you do use this
command, realize that the source tree is preserved.
+Use ``devtool ide`` to generate a configuration for the IDE
+-----------------------------------------------------------
+
+``devtool ide`` automatically configures IDEs for cross-compiling and remote
debugging.
+
+Two different use cases are supported:
+
+#. *Recipe mode*: Generate the IDE configuration for a workspace created by
``devtool modify``.
+
+ In order to use the tool, a few settings must be made.
+ As a starting example, the following lines of code can be added to the
local.conf file.
+
+ .. code-block::
+
+ # Build the companion debug file system
+ IMAGE_GEN_DEBUGFS = "1"
+ # Optimize build time: with devtool ide the dbg tar is not needed
+ IMAGE_FSTYPES_DEBUGFS = ""
+
+ # ssh is mandatory, no password simplifies the usage
+ EXTRA_IMAGE_FEATURES += "\
+ ssh-server-openssh \
+ debug-tweaks \
+ "
+
+ # Remote debugging needs the gdbserver on the target device
+ IMAGE_INSTALL:append = " gdbserver"
+
+ 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:
+
+ .. code-block::
+
+ $ 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 ``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``: configure 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.
+
+ It's possible to pass multiple recipes to the ``devtool ide`` command.
+ ``devtool ide`` tries to handle the recipes in a reasonable way if possible.
+
+ ``devtool ide`` aims to support multiple programming languages and multiple
IDEs natively.
+ Native means that the IDE is configured to call the build tool (e.g. cmake
or meson) directly.
+ This has several advantages. First of all, it is much faster than ``devtool
build``, for example.
+ But it also allows to use the very good integration of tools like CMake or
GDB directly with VSCode or other IDEs.
+ However, supporting many programming languages and multiple IDEs is quite
an elaborate and constantly evolving thing.
+ To handle combinations that are not natively supported, devtool ide creates
a configuration that falls back
+ to ``devtool build`` and ``devtool deploy-target`` if there is no native
support available.
+
+ 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.
+
+ .. note::
+
+ To ensure that the debug symbols on the build machine match the binaries
running on the target system,
+ it is essential that the image built by ``devtool ide`` is running on
the target system.
+
+#. *Shared sysroots mode*: Generate the IDE configuration for using a
cross-toolchain as provided by
+ ``bitbake meta-ide-support build-sysroots``.
+
+ 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.
+
+ .. code-block::
+
+ $ 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.
+
+ For some special recipes and use cases a 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.
+
+ .. code-block::
+
+ $ 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 following example shows how the
cross-toolchain can be
+ selected in VSCode.
+
+
+ .. code-block::
+
+ mkdir kit-test
+ echo "project(foo VERSION 0.1)" > kit-test/CMakeLists.txt
+ code kit-test
+
+ Ctrl + Shift + P --> CMake: Scan for Kits
+ Ctrl + Shift + P --> CMake: Select a Kit
+
Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a
Newer Version of the Software
-------------------------------------------------------------------------------------------------------
--
2.41.0
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#189820):
https://lists.openembedded.org/g/openembedded-core/message/189820
Mute This Topic: https://lists.openembedded.org/mt/102285623/21656
Group Owner: openembedded-core+ow...@lists.openembedded.org
Unsubscribe: https://lists.openembedded.org/g/openembedded-core/unsub
[arch...@mail-archive.com]
-=-=-=-=-=-=-=-=-=-=-=-
