[v8,8/8] docs: cover devtool ide

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.freihofer@siemens.com>
---
 documentation/sdk-manual/extensible.rst | 153 +++++++++++++++++++++++-
 1 file changed, 152 insertions(+), 1 deletion(-)

Hi Adrian,

Please at least Cc the docs mailing list :) The docs is actually handled 
in a separate repo (well the yocto docs, for bitbake it's in the bitbake 
mono-repo along side the code), by different people.

Cc'ing docs.

First, thanks for sending documentation related to a new feature while 
it's being developed, this is very much appreciated.

As an overall comment, I feel like the documentation about the internal 
working is not necessary. The user shouldn't care about what the tools 
does internally, only how to use it and configure it. If somehow it is 
broken, not supporting a specific use-case or feature, then a look at 
the code is warranted, where the documentation of the internals is desired.
The part I'm talking about is the one between
+   Here is what it does for a recipe which inherits the 
:ref:`ref-classes-cmake` class:
and
+   It's possible to pass multiple recipes to the ``devtool ide`` command.

Other comments inline, only typos. I have never used VSCode and I'm not 
knowledgeable in Meson nor Cmake nor SDKs so that all i could contribute 
to this patch review :)

On 11/1/23 12:01, Adrian Freihofer via lists.openembedded.org wrote:
> 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.freihofer@siemens.com>
> ---
>   documentation/sdk-manual/extensible.rst | 153 +++++++++++++++++++++++-
>   1 file changed, 152 insertions(+), 1 deletion(-)
> 
> diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst
> index 355c6cb0e4a..51d9fff2638 100644
> --- a/documentation/sdk-manual/extensible.rst
> +++ b/documentation/sdk-manual/extensible.rst
> @@ -63,6 +63,8 @@ their own pros and cons:
>      need to provide a well-functioning binary artefact cache over the network
>      for developers with underpowered laptops.
>   
> +.. _setting_up_ext_sdk_in_build:
> +
>   Setting up the Extensible SDK environment directly in a Yocto build
>   -------------------------------------------------------------------
>   
> @@ -230,13 +232,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:
>   

Just remove the number so we don't have to maintain it.

>   -  *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 +618,153 @@ 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:
> +

Ditto.

> +#. *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::
> +
> +      # 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::
> +
> +      $ 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.
> +   Here is what it does for a recipe which inherits the :ref:`ref-classes-cmake` class:
> +
> +   - 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

s/with/which/

s/environent/environment/

> +     the same CMmake cache configuration as used by ``bitbake recipe``. The CMake preset referres

s/referres/refers/

> +     to the per-recipe-sysroot of the recipe.
> +

s/per-recipe-sysroot/per-recipe sysroot/

> +     Currently Configure, Build and Test presets are supported. Test presets execute the test
> +     binaries with Qemu (qemu-user not qemu-system).
> +
> +   - Generate a helper script to handle the ``do_install`` with pseudo.
> +

Please use a reference for do_install. :ref:`ref-tasks-install`

> +   - Generate a helper script which does the same as ``devtool deploy-target`` does.
> +     Therefore ``devtool ide`` supports the same set of target related command line parameters
> +     as ``devtool deploy-target`` does.
> +     The ``--target`` parameter in the example above is just an example for that. It is optional.
> +
> +   - Generate some helper scripts to start ``gdbserver`` on the target device.
> +
> +   - Generate the ``.vscode`` folder containing the following files:
> +
> +   - ``c_ccp_properties.json``: Configure IntelliSense for 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 and in the rootfs-dbg folder

s/debug-symbols/debug symbols/
s/build-folder/build folder/ maybe actually provide the variable name 
(if there's one) so we know where to look (because I don't really know 
what this actually means in terms of paths).

> +     which is provided by the image recipe passed to the ``devtool ide`` command.
> +
> +   - ``settings.json``: Configure the code indexers to ignore the build folders.
> +     Without reasonable exclude settings, it is very likely that some indexer plugins will run
> +     with 100% CPU load until an OOM exception occurs. In the case of VSCode, the indexers started
> +     immediately and do not stop or reconfigure when the ignore list is updated. This means that the
> +     settings.json file must be available before VSCode is started in the workspace folder or before
> +     ``devtool modify`` has added the ``oe-workdir`` symlink to the large build folder of ``bitbake``.
> +
> +   - ``tasks.json``: Provide some helpers for running
> +

s/running//

> +      - :ref:`ref-tasks-install` and ``devtool deploy-target``
> +

+running
at the beginning of the bullet point

> +      - start ``gdbserver`` via ssh
> +

s/start/starting/


> +   For a recipe which inherits the :ref:`ref-classes-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.
> +
> +   - 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 icon`` 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.
> +
> +     Starting a remote debugging sesssion automatically initiates the deployment to the target device.
> +     If this is not desired, the ``"dependsOn": ["install && deploy-target...]`` parameter of the tasks
> +     with ``"label": "gdbserver start...`` can be removed from the ``tasks.json`` file.
> +
> +   Additionally ``--ide=none`` is supported.
> +   With the none IDE parameter some generic configurations files like ``.gdbinit`` files and some helper scripts
> +   starting the gdbserver remotely on the target device as well as the gdb client on the host 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.

s/per-recipe-sysroot/per-recipe sysroot/

> +   Therefore ``devtool ide`` also supports setting up the shared sysroots environment and generating
> +   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
> +
> +   For VSCode the cross-tool-chain is exposed as a CMake kit. CMake kits are defined in
> +   ``~/.local/share/CMakeTools/cmake-tools-kits.json``.
> +   The following minimalistic example shows how the cross-toolchain can be selected in VSCode.

s/minimalistic/minimalist/ (or just remove the word entirely)

> +   Fist of all we create a minimalistic CMake project and start VSCode::
> +

Ditto.

> +      mkdir kit-test
> +      echo "project(foo VERSION 1.0)" > kit-test/CMakeLists.txt
> +      code kit-test
> +
> +   If there is a CMake project in the workspace cross-compilation is supported:
> +
> +   - Press ``Ctrl + Shift + P``, type ``CMake: Scan for Kits``
> +   - Press ``Ctrl + Shift + P``, type ``CMake: Select a Kit``
> +
> +   For other IDEs than VSCode ``devtool ide none ...`` is just a simple wrapper for the
> +   setup of the extensible SDK as decribed in :ref:`setting_up_ext_sdk_in_build`.
> +

s/decribed/described/

Cheers,
Quentin

Hi Michael, hi Quentin

Sent a new version to the docs mailing list:
https://lists.yoctoproject.org/g/docs/message/4578

I hope this will address all your findings and I also hope that the v8
of the devtool ide will be accepted soon.

Adrian