From patchwork Thu Oct 15 20:06:32 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: AdrianF X-Patchwork-Id: 100911 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id E7A49CC6B38 for ; Thu, 15 Oct 2026 20:08:05 +0000 (UTC) Received: from mta-65-227.siemens.flowmailer.net (mta-65-227.siemens.flowmailer.net [185.136.65.227]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.6601.1792094874763602258 for ; Thu, 15 Oct 2026 13:07:56 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=adrian.freihofer@siemens.com header.s=fm2 header.b=LsVuVbSO; spf=pass (domain: rts-flowmailer.siemens.com, ip: 185.136.65.227, mailfrom: fm-1329275-20261015200752ecc4d41be70002070c-do5h9a@rts-flowmailer.siemens.com) Received: by mta-65-227.siemens.flowmailer.net with ESMTPSA id 20261015200752ecc4d41be70002070c for ; Thu, 15 Oct 2026 22:07:52 +0200 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; s=fm2; d=siemens.com; i=adrian.freihofer@siemens.com; h=Date:From:Subject:To:Message-ID:MIME-Version:Content-Type:Content-Transfer-Encoding:Cc:References:In-Reply-To; bh=1P0Jxv5k++iMzprsO9kPvO4fGrX7OTTYPfvtg4K3U/s=; b=LsVuVbSOYKhIKgzj3NI6DyBGV0IcGJfU9dBVK2byey2hMafmwU5fgD7dWSsZfk9ZdqtYOe drLCOtvtOw4HdvzaNr96CrMdZVpxlpM3paMSYaVnnW7xV9eGRP2AgDERjJ9q2pWdT98TTg5T zOtB4XMwGz5YdSvNyAklTkF2ohuzp1gFtWb5bc1JUK1l35P5qjIuvZ+/Hy4h+U/e0bLhoj4s UpFcxuygms4aPV/OTOSWep4Oq3BFqRUywQQXxhjCp6z4v12zss653jQf4t/rjpVzR5UQfqNK /b4BiYJAVtQCpLtihblDpNP7PUZAo1dLtNvDfQus+oeyJFO8OZKaSBxQ==; From: AdrianF To: docs@lists.yoctoproject.org Cc: Adrian Freihofer Subject: [PATCH v3 1/4] dev-manual/devtool: fix non-patch local file handling docs Date: Thu, 15 Oct 2026 22:06:32 +0200 Message-ID: <20261015200726.2391599-2-adrian.freihofer@siemens.com> In-Reply-To: <20261015200726.2391599-1-adrian.freihofer@siemens.com> References: <20261015200726.2391599-1-adrian.freihofer@siemens.com> MIME-Version: 1.0 X-Flowmailer-Platform: Siemens Feedback-ID: 519:519-1329275:519-21489:flowmailer List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 15 Oct 2026 20:08:05 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10685 From: Adrian Freihofer Non-patch ``file://`` entries in :term:`SRC_URI` no longer end up in an ``oe-local-files`` folder: that mechanism, along with ``S = WORKDIR``, was removed in 5.1 (see migration-5.1.rst). Whether such files reach ``srctree`` now depends on :term:`S`: they land directly in ``srctree`` only if the recipe sets ``S = "${UNPACKDIR}"``; otherwise they are unpacked into :term:`UNPACKDIR` outside of ``S`` and never reach ``srctree``, so they must be edited next to the recipe instead. Update the ``devtool modify``/``extract``/``upgrade``/``finish`` descriptions accordingly. Signed-off-by: Adrian Freihofer --- documentation/dev-manual/devtool.rst | 91 +++++++++++++++++++--------- 1 file changed, 61 insertions(+), 30 deletions(-) diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst index 242ea9dd9..1f22fb799 100644 --- a/documentation/dev-manual/devtool.rst +++ b/documentation/dev-manual/devtool.rst @@ -231,15 +231,27 @@ command: append file within the workspace while the recipe remains in its original location. - Additionally, if you have any non-patch local files (i.e. files - referred to with ``file://`` entries in :term:`SRC_URI` statement - excluding ``*.patch/`` or ``*.diff``), these files are copied to - an ``oe-local-files`` folder under the newly created source tree. - Copying the files here gives you a convenient area from which you - can modify the files. Any changes or additions you make to those - files are incorporated into the build the next time you build the - software just as are other changes you might have made to the - source. + Additionally, any non-patch local files (i.e. files referred to + with ``file://`` entries in the recipe's :term:`SRC_URI` + statement, excluding ``*.patch`` or ``*.diff`` files) only end up + in the extracted source tree if the recipe sets + ``S = "${UNPACKDIR}"``. In that case, they are unpacked directly + into the source tree at the same location as the upstream source, + mixed in with the rest of the unpacked source with no separate + area to identify them, so you need to check the recipe's + :term:`SRC_URI` to tell which files came from local ``file://`` + entries. You can edit them directly in the source tree, and any + changes you make are incorporated into the build the next time + you build the software just as are other changes you might have + made to the upstream source. + + If instead :term:`S` is a subdirectory of :term:`UNPACKDIR` (the + traditional default, e.g. ``S = "${UNPACKDIR}/${BP}"``), these + local files are unpacked into :term:`UNPACKDIR` but outside of + :term:`S`, so they never end up in the source tree at all. They + remain purely recipe-side, and are unpacked again into the + recipe's real :term:`WORKDIR` on every subsequent build regardless + of ``devtool modify``; edit them next to the recipe instead. - *Middle*: The middle scenario in the figure represents a situation where the source code also does not exist locally. In this case, @@ -260,8 +272,10 @@ command: As with all extractions, the command uses the recipe's :term:`SRC_URI` statements to locate the source files and any associated patch - files. Non-patch files are copied to an ``oe-local-files`` folder - under the newly created source tree. + files. Non-patch files only end up in ``srctree`` if the recipe + sets ``S = "${UNPACKDIR}"``; otherwise they are unpacked into + :term:`UNPACKDIR` but outside of :term:`S` and never reach + ``srctree`` at all. Once the files are located, the command by default extracts them into ``srctree``. @@ -283,12 +297,15 @@ command: $ devtool modify -n recipe srctree - If an ``oe-local-files`` subdirectory happens to exist and it - contains non-patch files, the files are used. However, if the - subdirectory does not exist and you run the ``devtool finish`` - command, any non-patch files that might exist next to the recipe - are removed because it appears to ``devtool`` that you have - deleted those files. + For a recipe that sets ``S = "${UNPACKDIR}"``, non-patch local + files are expected to already be present directly in ``srctree`` + at the same location as the upstream source. If they are missing + there and you run the ``devtool finish`` command, any non-patch + files that might exist next to the recipe are removed because it + appears to ``devtool`` that you have deleted those files. This + does not apply if :term:`S` is a subdirectory of + :term:`UNPACKDIR`, since in that case the local files never lived + in ``srctree`` to begin with. Once the ``devtool modify`` command finishes, it creates only an append file for the recipe in the ``devtool`` workspace. The @@ -356,9 +373,10 @@ command: Because there is no need to move the recipe, ``devtool finish`` either updates the original recipe in the original layer or the command creates a ``.bbappend`` file in a different layer as provided - by layer. Any work you did in the ``oe-local-files`` directory is - preserved in the original files next to the recipe during the - ``devtool finish`` command. + by layer. If the recipe sets ``S = "${UNPACKDIR}"``, any changes you + made directly to local files in the source tree are written back to + the original files next to the recipe during the ``devtool finish`` + command. As a final process of the ``devtool finish`` command, the state of the standard layers and the upstream source is restored so that you @@ -811,14 +829,26 @@ The following diagram shows the common development flow used with the the new version of the recipe, and an append file all within the workspace. - Additionally, if you have any non-patch local files (i.e. files - referred to with ``file://`` entries in :term:`SRC_URI` statement - excluding ``*.patch/`` or ``*.diff``), these files are copied to an - ``oe-local-files`` folder under the newly created source tree. - Copying the files here gives you a convenient area from which you can - modify the files. Any changes or additions you make to those files - are incorporated into the build the next time you build the software - just as are other changes you might have made to the source. + Additionally, any non-patch local files (i.e. files referred to with + ``file://`` entries in the recipe's :term:`SRC_URI` statement, + excluding ``*.patch`` or ``*.diff`` files) only end up in the + extracted source tree if the recipe sets ``S = "${UNPACKDIR}"``. In + that case, they are unpacked directly into the source tree at the + same location as the upstream source, mixed in with the rest of the + unpacked source with no separate area to identify them, so you need + to check the recipe's :term:`SRC_URI` to tell which files came from + local ``file://`` entries. You can edit them directly in the source + tree, and any changes you make are incorporated into the build the + next time you build the software just as are other changes you might + have made to the upstream source. + + If instead :term:`S` is a subdirectory of :term:`UNPACKDIR` (the + traditional default, e.g. ``S = "${UNPACKDIR}/${BP}"``), these local + files are unpacked into :term:`UNPACKDIR` but outside of :term:`S`, + so they never end up in the source tree at all. They remain purely + recipe-side, and are unpacked again into the recipe's real + :term:`WORKDIR` on every subsequent build regardless of + ``devtool upgrade``; edit them next to the recipe instead. #. *Resolve any Conflicts created by the Upgrade*: Conflicts could happen after upgrading the software to a new version. Conflicts occur @@ -877,8 +907,9 @@ The following diagram shows the common development flow used with the resets the recipe so that the recipe is built normally rather than from the workspace. - Any work you did in the ``oe-local-files`` directory is preserved in - the original files next to the recipe during the ``devtool finish`` + If the recipe sets ``S = "${UNPACKDIR}"``, any changes you made + directly to local files in the source tree are written back to the + original files next to the recipe during the ``devtool finish`` command. If you specify a destination layer that is the same as the original From patchwork Thu Oct 15 20:06:33 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: AdrianF X-Patchwork-Id: 100912 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4A0E0CCA467 for ; Thu, 15 Oct 2026 20:08:06 +0000 (UTC) Received: from mta-65-225.siemens.flowmailer.net (mta-65-225.siemens.flowmailer.net [185.136.65.225]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.6602.1792094875809577453 for ; Thu, 15 Oct 2026 13:07:56 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=adrian.freihofer@siemens.com header.s=fm2 header.b=oyzuAwgG; spf=pass (domain: rts-flowmailer.siemens.com, ip: 185.136.65.225, mailfrom: fm-1329275-20261015200754c8b9d3d6d800020796-vkc3he@rts-flowmailer.siemens.com) Received: by mta-65-225.siemens.flowmailer.net with ESMTPSA id 20261015200754c8b9d3d6d800020796 for ; Thu, 15 Oct 2026 22:07:54 +0200 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; s=fm2; d=siemens.com; i=adrian.freihofer@siemens.com; h=Date:From:Subject:To:Message-ID:MIME-Version:Content-Type:Content-Transfer-Encoding:Cc:References:In-Reply-To; bh=Y9WllHhis1gONOKLhfL2XlpDXxhjFO0e5sOswi8ufBY=; b=oyzuAwgGdoYzo6HDoGQe8CYPbeHhfVRtyEuWjp7GZYQHaqZD4NCLTpwLieeFYP+JDz/wC6 e1COOhEoj11JeXaTp7OE44y3ttXXpFSS1KxrEbW8/oIfnn+bOQd+tN0cqZFmR2JtL3FiGrvr 4kL7L5fi/hSoAd8Ii/4uyE7DJBu50cVBfN0noSFfpo/mtNFj6BzA1T7cqsd8QH/Zr45wapqs kASMtFx3gja0Kd+d7oCwOyYugmLdgo+3WFjVG9bTj1mBx/83PcdPSb8MFbxvLJWavr/1qlWS F8bUt69OMNFkAxUhFGpfVLqeDvI7Wx7ekwm79op/NY5/Qmj64KRyzqyw==; From: AdrianF To: docs@lists.yoctoproject.org Cc: Adrian Freihofer Subject: [PATCH v3 2/4] dev-manual/devtool: update devtool ide-sdk section for recent features Date: Thu, 15 Oct 2026 22:06:33 +0200 Message-ID: <20261015200726.2391599-3-adrian.freihofer@siemens.com> In-Reply-To: <20261015200726.2391599-1-adrian.freihofer@siemens.com> References: <20261015200726.2391599-1-adrian.freihofer@siemens.com> MIME-Version: 1.0 X-Flowmailer-Platform: Siemens Feedback-ID: 519:519-1329275:519-21489:flowmailer List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 15 Oct 2026 20:08:06 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10687 From: Adrian Freihofer Document the devtool ide-sdk features added since this section was last updated: automatic image debug settings, --nfs, --package/--file-glob, combining modified and shared mode, IntelliSense selection and further native tools. Also document the local rootfs path and --package/--file-glob support of "devtool deploy-target". Signed-off-by: Adrian Freihofer --- documentation/dev-manual/devtool.rst | 971 ++++++++++++------ .../ref-manual/devtool-reference.rst | 3 + 2 files changed, 660 insertions(+), 314 deletions(-) diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst index 1f22fb799..e182b427b 100644 --- a/documentation/dev-manual/devtool.rst +++ b/documentation/dev-manual/devtool.rst @@ -107,6 +107,14 @@ command: From within the editor, you can make modifications to the recipe that take effect when you build it later. + .. note:: + + As an alternative to the ``edit-recipe``/``build``/``deploy-target`` + loop, you can use :ref:`devtool-ide-sdk-section` to generate an SDK + and an IDE configuration once, and then edit, build and deploy + directly from the IDE, without going through ``devtool`` or + ``bitbake`` for every change. + #. *Build the Recipe or Rebuild the Image*: The next step you take depends on what you are going to do with the new code. @@ -141,6 +149,19 @@ command: $ devtool deploy-target recipe target The target is a live target machine running as an SSH server. + Alternatively, ``target`` can be an absolute path to a local + pseudo-managed rootfs directory (e.g. one extracted by + ``runqemu-extract-sdk``, see + :ref:`dev-manual/qemu:running under a network file system (nfs) server`), + in which case the files are copied into it directly, without SSH. + + By default, every file installed by the recipe is deployed (except files + that only end up in a ``-staticdev``, ``-dbg`` or ``-src`` package, which + are not useful on a live target). Use the ``--package`` and/or + ``--file-glob`` options to deploy only a subset of the installed files + instead, for example ``--package my-recipe-tests`` or + ``--file-glob "/usr/bin/*"``. Both options may be given multiple times and + combined. You can, of course, also deploy the image you build to actual hardware by using the ``devtool build-image`` command. However, @@ -315,6 +336,14 @@ command: you are free to make changes to the source files. You can use any editor you like to make and save your source code modifications. + .. note:: + + As an alternative to the manual edit/``build``/``deploy-target`` + loop, you can use :ref:`devtool-ide-sdk-section` to generate an SDK + and an IDE configuration once, and then edit, build and deploy + directly from the IDE, without going through ``devtool`` or + ``bitbake`` for every change. + #. *Build the Recipe or Rebuild the Image*: The next step you take depends on what you are going to do with the new code. @@ -349,6 +378,9 @@ command: $ devtool deploy-target recipe target The target is a live target machine running as an SSH server. + Alternatively, ``target`` can be an absolute path to a local + pseudo-managed rootfs directory, in which case the files are copied + into it directly, without SSH. You can, of course, use other methods to deploy the image you built using the ``devtool build-image`` command to actual hardware. @@ -388,14 +420,15 @@ command: decide you do not want to proceed with your work. If you do use this command, realize that the source tree is preserved. +.. _devtool-ide-sdk-section: + ``devtool ide-sdk`` configures IDEs and bootstraps SDKs ======================================================= -The ``devtool ide-sdk`` command can provide an IDE configuration for IDEs when -working on the source code of one or more recipes. -Depending on the programming language, and the build system used by the recipe, -the tools required for cross-development and remote debugging are different. -For example: +The ``devtool ide-sdk`` command configures an IDE for working on the source +code of one or more recipes. The tools required for cross-development and +remote debugging depend on the recipe's programming language and build +system. For example: - A C/C++ project usually uses CMake or Meson. @@ -403,9 +436,9 @@ For example: - A Rust project uses Cargo. -Also, the IDE plugins needed for the integration of a build system with the -IDE and the corresponding settings are usually specific to these build-systems. -To hide all these details from the user, ``devtool ide-sdk`` does two things: +The IDE plugins needed to integrate a build system with the IDE, and their +corresponding settings, are usually specific to that build system too. To +hide these details from the user, ``devtool ide-sdk`` does two things: - It generates any kind of SDK needed for cross-development and remote debugging of the specified recipes. @@ -414,11 +447,104 @@ To hide all these details from the user, ``devtool ide-sdk`` does two things: the cross-toolchain and remote debugging tools provided by the SDK directly from the IDE. -For supported build systems the configurations generated by ``devtool ide-sdk`` -combine the advantages of the ``devtool modify`` based workflow -(see :ref:`using_devtool`) with the advantages of the simple Environment Setup -script based workflow (see :ref:`running_the_ext_sdk_env`) provided by Yocto's -SDK or eSDK: +``devtool ide-sdk`` can do this in one of two modes: the default +:ref:`"modified" ` mode, which uses the +workspace created by ``devtool modify`` together with BitBake's per-recipe +:term:`Sysroots `; and +:ref:`"shared" ` mode +(``--mode=shared``), which instead bootstraps a full SDK/eSDK-like +environment with shared :term:`Sysroots `, for cases where the +default ``devtool``/``bitbake`` integration is not suitable. Both modes can +also be :ref:`combined ` +by repeating the ``--mode`` option. All of this is covered in more detail +below. + +Modified mode +------------- + +Design and architecture +^^^^^^^^^^^^^^^^^^^^^^^^ + +A key point of this design is that generating the SDK and the IDE +configuration is a separate step from actually working on the code. This is +what sets ``devtool ide-sdk`` apart from the ``devtool build`` based workflow +(see :ref:`using_devtool`), where every edit/build/deploy/test iteration goes +through ``devtool build`` and +``devtool deploy-target``, and therefore through ``bitbake``, every time. +``devtool ide-sdk`` is itself a ``bitbake`` ``tinfoil`` client, but it drives +``bitbake`` only to generate the SDK, i.e. to build the recipe (and the +image) so that their :term:`WORKDIR` is fully populated. Once the SDK is +there, editing the source code, building, deploying and debugging all happen +directly in the IDE, independently of ``devtool ide-sdk`` and without calling +``bitbake`` for every change: ``devtool ide-sdk`` generates an IDE +configuration that points the IDE directly at the build tool, the +cross-toolchain and the debugger provided by the SDK. ``devtool ide-sdk`` +only needs to be re-run later on, e.g. if a recipe's dependencies or its +build configuration change. + +Let's now take a closer look at how ``devtool ide-sdk`` and the generated IDE +configuration make use of a regular ``bitbake`` environment as a SDK to +achieve this, covering both the build and the remote debug session. +``devtool ide-sdk`` needs at least one recipe in ``devtool modify`` state +(i.e. using :ref:`ref-classes-externalsrc` to build from the workspace) and +an image recipe that is used for the development. ``devtool ide-sdk`` reads +all the details of how ``bitbake`` builds the recipe via the ``tinfoil`` +API, and uses this information to: + +- Call ``bitbake`` to compile all the parts of the SDK. + +- Replicate ``bitbake``'s exact build configuration into an IDE configuration + for working on that recipe's source; a separate IDE configuration, i.e. a + separate recipe workspace instance (see below), is generated for every + recipe. + +The recipe's :term:`WORKDIR` already contains everything needed for +cross-development. Let's briefly recap how ``bitbake`` normally builds a +recipe, up to :ref:`ref-tasks-install`: + +- :ref:`ref-tasks-configure` and :ref:`ref-tasks-compile` build the + sources into :term:`B`, the build directory, using the native, + host-runnable tools in :term:`RECIPE_SYSROOT_NATIVE` + (``recipe-sysroot-native``) --- e.g. the build tool (``cmake``), the + cross-compiler, and the debugger (``gdb``) --- against the target + headers and libraries in :term:`RECIPE_SYSROOT` (``recipe-sysroot``). + +- :ref:`ref-tasks-install` installs the compiled output (``make install``) + into :term:`D` (``image``), where the unstripped, but relocated binaries, + as well as additionally installed files, end up. + +The exact same tools and locations are used by an IDE configured by +``devtool ide-sdk``. The source code itself, :term:`S`, is not +part of ``WORKDIR`` in this workflow: it is the source tree extracted by +``devtool modify`` into the ``devtool`` workspace, which is exactly where +the IDE opens and edits it. From this, ``devtool ide-sdk`` +generates an IDE configuration (e.g. a build tool preset and a debugger +launch configuration) that simply points the IDE at the existing build +tool binary in ``recipe-sysroot-native``. From then on, the IDE calls +that build tool directly, without going through ``devtool ide-sdk`` or +``bitbake`` again, but with the exact same configuration ``bitbake`` or +``devtool build`` would use, e.g. a generated CMakePreset or Meson cross +file that points to the cross-compiler in +``recipe-sysroot-native`` and the target sysroot in ``recipe-sysroot``. + +For remote debugging, the IDE manages a debugger (e.g. GDB) on the host +instead --- the debugger itself is one of those native tools in +``recipe-sysroot-native`` too. The debugger gets its debug symbols for +the recipe's own binary from ``D``, and for every other shared library on +the target from the ``rootfs-dbg`` directory in the image recipe's +``WORKDIR`` (see the note above about ``image-combined-dbg``). The +debugger then connects to a debug-server (e.g. ``gdbserver``) running on +the target device, which launches or attaches to the actual application +binary there. + +The same architecture also allows the IDE to be configured to use further +tools beyond the build tool, cross-compiler and debugger, e.g. +``clang-tidy``: any such tool just needs to be added as a native tool in +``recipe-sysroot-native``, in the Yocto reproducible way, for +``devtool ide-sdk`` to be able to point the IDE at it. + +To summarize the design described above, for supported build systems +modified mode brings two key benefits: - The source code of the recipe is in the workspace created by ``devtool modify`` or ``devtool add``. @@ -428,333 +554,547 @@ SDK or eSDK: configuration at any time. - ``devtool ide-sdk`` aims to support multiple programming languages and - multiple IDEs natively. "Natively" 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 usually much faster to call for example ``cmake`` than - ``devtool build``. - It also allows to benefit from the very good integration that IDEs like - VSCode offer for tools like CMake or GDB. - - However, supporting many programming languages and multiple - IDEs is quite an elaborate and constantly evolving thing. Support for IDEs - is therefore implemented as plugins. Plugins can also be provided by - optional layers. - -So much about the introduction to the default mode of ``devtool sdk-ide`` which -is called the "modified" mode because it uses the workspace created by -``devtool modify`` and the per recipe :term:`Sysroots ` of BitBake. - -For some recipes and use cases, this default behavior of ``devtool ide-sdk`` -with full ``devtool`` and ``bitbake`` integration might not be suitable. -To offer full feature parity with the SDK and the eSDK, ``devtool ide-sdk`` has -a second mode called "shared" mode. -If ``devtool ide-sdk`` is called with the ``--mode=shared`` option, it -bootstraps an SDK directly from the BitBake environment, which offers the same -Environment Setup script as described in :ref:`running_the_ext_sdk_env`. -In addition to the (e)SDK installer-based setup, the IDE gets configured -to use the shared :term:`Sysroots ` and the tools from the SDK. -``devtool ide-sdk --mode=shared`` is basically a wrapper for the setup of the -extensible SDK as described in :ref:`setting_up_ext_sdk_in_build`. - -The use of ``devtool ide-sdk`` is an alternative to using one of the SDK -installers. -``devtool ide-sdk`` allows the creation of SDKs that offer all the -functionality of the SDK and the eSDK installers. Compared to the installers, -however, the SDK created with ``devtool ide-sdk`` is much more flexible. -For example, it is very easy to change the :term:`MACHINE` in the -:ref:`structure-build-conf-local.conf` file, update the layer meta data and then regenerate the SDK. - -Let's take a look at an example of how to use ``devtool ide-sdk`` in each of -the two modes: - -#. *Modified mode*: - - In order to use the ``devtool ide-sdk``, a few settings are needed. As a - starting example, the following lines of code can be added to the - :ref:`structure-build-conf-local.conf` file:: - - # Build the companion debug file system - IMAGE_GEN_DEBUGFS = "1" - # Optimize build time: with devtool ide-sdk the dbg tar is not needed - IMAGE_FSTYPES_DEBUGFS = "" - # Without copying the binaries into roofs-dbg, GDB does not find all source files. - IMAGE_CLASSES += "image-combined-dbg" - - # SSH is mandatory, no password simplifies the usage - EXTRA_IMAGE_FEATURES += "\ - ssh-server-openssh \ - allow-empty-password \ - allow-root-login \ - empty-root-password \ - " - - # Remote debugging needs gdbserver on the target device - IMAGE_INSTALL:append = " gdbserver" - - # Add the recipes which should be modified to the image - # Otherwise some dependencies might be missing. - IMAGE_INSTALL:append = " my-recipe" - - Assuming the BitBake environment is set up correctly and a workspace has - been created for the recipe using ``devtool modify my-recipe`` or probably - even better by using ``devtool modify my-recipe --debug-build``, the - following command can create the SDK and the configuration for VSCode in - the recipe workspace:: - - $ devtool ide-sdk my-recipe core-image-minimal --target root@192.168.7.2 - - The command requires an image recipe (``core-image-minimal`` for this - example) that is used to create the SDK. - This firmware image should also be installed on the target device. - It is possible to pass multiple package recipes:: - - $ devtool ide-sdk my-recipe-1 my-recipe-2 core-image-minimal --target root@192.168.7.2 - - ``devtool ide-sdk`` tries to create an IDE configuration for all package - recipes. - - What this command does exactly depends on the recipe, more precisely on the - build tool used by the recipe. The basic idea is to configure the IDE so - that it calls the build tool exactly as ``bitbake`` does. - - For example, a CMake preset is created for a recipe that inherits - :ref:`ref-classes-cmake`. In the case of VSCode, CMake presets are supported - by the CMake Tools plugin. This is an example of how the build configuration - used by ``bitbake`` is exported to an IDE configuration that gives exactly - the same build results. - - Support for remote debugging with seamless integration into the IDE is - important for a cross-SDK. ``devtool ide-sdk`` automatically generates the - necessary helper scripts for deploying the compiled artifacts to the target - device as well as the necessary configuration for the debugger and the IDE. - - .. note:: - - To ensure that the debug symbols on the build machine match the binaries - running on the target device, it is essential that the image built by - ``devtool ide-sdk`` is running on the target device. - - The default IDE is VSCode. Some hints about using VSCode: - - - VSCode can be used to work on the BitBake recipes or the application - source code. - Usually there is one instance of VSCode running in the folder where the - BitBake recipes are. This instance has the - `Yocto Project BitBake plugin `_ - running. - - .. warning:: - - Some VSCode plugins (Python, BitBake and others) need a reasonable - configuration to work as expected. Otherwise, some plugins try to - index the build directory of BitBake, which keeps your system quite - busy until an out of memory exception stops this nonsense. - Other plugins, such as the BitBake plugin, do not behave as expected. - - To work around such issues, the ``oe-init-build-env`` script creates - an initial ``.vscode/settings.json`` file if ``code`` can be found - and the ``.vscode`` folder does not yet exist. - It is best to run ``oe-init-build-env`` once before starting VSCode. - An alternative approach is to use a build folder outside the layers, - e.g. ``oe-init-build-env ../build``. - - The BitBake plugin also offers to create devtool workspaces and run - ``devtool ide-sdk`` with a few mouse clicks. - Of course, issuing commands in the terminal works as well. - - - To work on the source code of a recipe another instance of VSCode is - started in the recipe's workspace. Example:: - - code build/workspace/sources/my-recipe + multiple IDEs natively, meaning the IDE is configured to call the build + tool (e.g. ``cmake`` or ``meson``) directly. This has two main advantages: + it is usually much faster than calling ``devtool build``, and it lets you + benefit from the integration that IDEs like VSCode offer for tools such as + CMake or GDB. + + Supporting many programming languages and IDEs is an elaborate, + constantly evolving task, so support for IDEs is implemented as plugins. + Optional layers can also provide plugins. + + For recipes using a programming language or build system not yet supported + by ``devtool ide-sdk``, an IDE configuration which uses the + ``devtool build`` based workflow described above is generated as a + fallback. + +``devtool ide-sdk`` is an alternative to using one of the SDK installers, +i.e. the standard SDK built by the :ref:`ref-classes-populate-sdk` class +(``bitbake -c populate_sdk``) or the extensible SDK (eSDK) built by the +:ref:`populate_sdk_ext ` class +(``bitbake -c populate_sdk_ext``): it can create SDKs offering all the +functionality of the SDK and eSDK installers, but is much more flexible. +For example, it is very easy to change :term:`MACHINE` in the +:ref:`structure-build-conf-local.conf` file, update the layer metadata, and then regenerate the +SDK. When a :ref:`overview-manual/concepts:shared state cache` is +available, e.g. shared between developers or with the autobuilder, +building an SDK installer becomes less important in the first place, as +:doc:`bitbake-setup ` +can quickly replicate the layers and build configuration, and +``devtool ide-sdk`` can then quickly regenerate an equivalent SDK straight +from that cache. + +Let's take a look at an example of how to use ``devtool ide-sdk``. + +Setting up SSH access +^^^^^^^^^^^^^^^^^^^^^^ + +In order to use ``devtool ide-sdk``, SSH access to the target is needed, i.e. +the image needs an SSH server (``ssh-server-dropbear`` or +``ssh-server-openssh``). See the +":ref:`dev-manual/customizing-images:Customizing Images Using Custom \`\`IMAGE_FEATURES\`\` and \`\`EXTRA_IMAGE_FEATURES\`\``" +section for how to add it, and the ":ref:`ref-manual/features:image features`" +section of the Yocto Project Reference Manual for the related +``allow-root-login``, ``allow-empty-password`` and ``empty-root-password`` +features. To simplify usage during development, the +:ref:`ref-fragments-root-login-with-empty-password` configuration fragment +enables a passwordless root login over SSH. + +.. note:: + + ``devtool ide-sdk`` automatically adds everything else needed for + debugging, e.g. ``IMAGE_GEN_DEBUGFS``, ``IMAGE_FSTYPES_DEBUGFS``, the + :oecore_path:`image-combined-dbg ` + class, ``gdbserver``/``lldb-server``, and the + recipes being worked on. It writes only the settings it still needs + into the image recipe's ``.bbappend`` file in the workspace, and + removes them again once they are no longer required, so there is no + need to add any of this to ``local.conf`` manually. + +Generating the SDK and IDE configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Assuming the BitBake environment is set up correctly and a workspace has +been created for the recipe using ``devtool modify my-recipe`` (or, for a +more useful debug build, ``devtool modify my-recipe --debug-build``), the +following command can create the SDK and the configuration for VSCode in +the recipe workspace:: + + $ devtool ide-sdk my-recipe core-image-minimal --target root@192.168.7.2 + +The command requires an image recipe (``core-image-minimal`` for this +example) that is used to create the SDK. +This firmware image should also be installed on the target device. +It is possible to pass multiple package recipes:: + + $ devtool ide-sdk my-recipe-1 my-recipe-2 core-image-minimal --target root@192.168.7.2 + +If only an image recipe is passed, all recipes currently modified in the +workspace (i.e. everything with a ``/appends/*.bbappend`` file) +are used automatically, so the above is usually equivalent to just:: + + $ devtool ide-sdk core-image-minimal --target root@192.168.7.2 + +What exactly this command does depends on the build tool used by the +recipe. The basic idea is to configure the IDE to call the build tool +exactly as ``bitbake`` does. + +For example, for a recipe that inherits :ref:`ref-classes-cmake`, a CMake +preset is created; VSCode's CMake Tools plugin supports these presets +directly. This shows how the build configuration used by ``bitbake`` is +exported to an IDE configuration that produces exactly the same build +results. + +Seamless remote debugging support is important for a cross-SDK. +``devtool ide-sdk`` automatically generates the helper scripts needed to +deploy compiled artifacts to the target device, as well as the +configuration needed for the debugger and the IDE. + +.. note:: + + To ensure that the debug symbols on the build machine match the binaries + running on the target device, it is essential that the image built by + ``devtool ide-sdk`` is running on the target device. + +Debugging on a target +^^^^^^^^^^^^^^^^^^^^^^ + +The target is selected with ``--target``, which takes an SSH destination +(``[user@]host``, default ``root@192.168.7.2``), and ``--port`` if SSH listens +on a port other than 22. It can be a real device, a :doc:`QEMU ` instance or any other +device running the image built by ``devtool ide-sdk``. + +Every debug configuration consumes one debug server port on the target, +counting up from ``1234``. Use ``--gdbserver-port-start`` to start at a +different port, e.g. to run several ``devtool ide-sdk`` instances on the same +host at the same time. The option applies to all debug servers, i.e. to +``gdbserver`` as well as ``lldb-server``. + +If the ssh host key of the target changes frequently, e.g. because the target +is re-flashed often, use ``--no-host-check`` to disable ssh host key checking. + +QEMU target with slirp networking +""""""""""""""""""""""""""""""""" + +A QEMU target started with ``runqemu slirp`` (see the ``slirp`` option in +":ref:`dev-manual/qemu:\`\`runqemu\`\` command-line options`") needs no root +privileges, but is only reachable through forwarded host ports. +``devtool ide-sdk`` supports this +setup: it adds the port forwards required by the debug servers to +``QB_SLIRP_OPT`` in the image's ``.bbappend`` file, so that ``runqemu`` reads +them from the image's ``.qemuboot.conf`` file:: + + $ devtool ide-sdk my-recipe core-image-minimal --target root@localhost --port 2222 + $ runqemu slirp serialstdio snapshot + +QEMU instances reached through slirp get a new ssh host key on every boot. +Therefore, ssh host key checking is disabled automatically for the loopback +targets ``localhost``, ``127.0.0.1`` and ``::1``, and ``--no-host-check`` is +not needed. + +Booting the target from an NFS-exported root filesystem +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As an alternative to installing the image and deploying build output over +SSH for every debug session, ``devtool ide-sdk`` can boot the target from +an NFS-exported root filesystem, automating the manual +:ref:`dev-manual/qemu:running under a network file system (nfs) server` +workflow. Passing ``--nfs=rootfs`` (or ``--nfs=rootfs-dbg`` to also include +the debug filesystem) extracts the selected root filesystem below +``/nfs-exports//`` and generates a +``runqemu-rootfs``/``runqemu-rootfs-dbg`` helper script to boot QEMU with +that root filesystem mounted over NFS:: + + $ devtool ide-sdk my-recipe core-image-minimal --nfs=rootfs-dbg --target root@192.168.7.2 + $ build/workspace/nfs-exports/core-image-minimal/runqemu-rootfs-dbg nographic + +This changes the relationship between the SDK, the target device and the +debug symbols compared to the architecture described above: instead of a +separate ``rootfs`` booted by the target and a ``rootfs-dbg`` only +consulted by the debugger on the host, both the target and the debugger +now use the same NFS-exported ``rootfs-dbg``. + +Use ``--nfs-extract-dir=DIR`` to extract below ``DIR//`` +instead of the default location in the workspace, for example when the NFS +server may only export a particular directory. Note that every +``devtool ide-sdk --nfs`` run re-extracts the root filesystem from scratch, +which discards everything previously deployed into it. + +To boot a real hardware target instead of QEMU, ``devtool ide-sdk --nfs`` +also generates an ``export-hw-rootfs`` (or ``export-hw-rootfs-dbg``) helper +script next to the ``runqemu`` helper. It exports the root filesystem with +``runqemu-export-rootfs`` and serves :term:`DEPLOY_DIR_IMAGE` over HTTP +(port 8080 by default, set the ``PORT`` environment variable to change it), +so that a boot loader (e.g. U-Boot with its ``wget`` command) can fetch the +kernel while the root filesystem is mounted over NFS. Since the target +hardware and boot loader setup differ widely, this script covers the typical +case and is meant to be adapted as needed. Like the ``runqemu`` helper, it +requires the build environment to be sourced. + +Deploying build output then copies the recipe's build artifacts directly +into the exported directory on the host, without any SSH transfer: since +that directory already lives on the build machine rather than on a remote +target, ``devtool deploy-target`` only needs a local file copy there. + +Without ``--nfs=rootfs-dbg``, the debugger looks up the debug symbols and +source files of other recipes' shared libraries (i.e. everything besides +the recipe(s) being worked on) inside the ``rootfs-dbg`` folder of the +image's build directory, which is only refreshed by rebuilding the whole +image. With ``--nfs=rootfs-dbg``, those same lookups are pointed at the +NFS-exported ``rootfs-dbg`` instead --- the same directory the target +already boots from and that ``devtool deploy-target`` writes into. This +avoids rebuilding the whole image just to refresh debug information after +an incremental change, speeding up the edit/build/debug cycle. + +Since the target is booted directly from ``rootfs-dbg``, the debug symbols +are also present on the target itself, not just on the development host. +This relies on the +:oecore_path:`image-combined-dbg ` +class (see the note above, enabled automatically), which combines the +unstripped binaries and their debug symbols into ``rootfs-dbg``, unlike a +plain ``rootfs`` where symbols are split out into separate ``-dbg`` +packages that are not installed. +Having them together on the target makes tools like ``perf`` or +``trace-cmd``, run directly on the target, produce properly symbolicated +output. The same debug symbols are also useful to obtain test code +coverage. + +Using VSCode +^^^^^^^^^^^^ + +The default IDE is VSCode. Some hints about using VSCode: + +- VSCode can be used to work on the BitBake recipes or the application + source code. + Usually there is one instance of VSCode running in the folder where the + BitBake recipes are. This instance has the + `Yocto Project BitBake plugin `_ + running. + + .. warning:: + + Some VSCode plugins (Python, BitBake and others) try to index every + file in the workspace, which can make your system unusable while it + churns through large generated directories. A build environment set + up with ``bitbake-setup`` avoids this for this "meta" instance: it + generates (and keeps updated) a ``bitbake.code-workspace`` multi-root + workspace file with appropriate excludes for the layers and + ``build/conf``. For each per-recipe workspace instance (see below), + ``devtool ide-sdk`` generates its own ``settings.json`` with a + similar ignore list, excluding directories such as ``oe-workdir`` + and ``oe-logs``. + + The BitBake plugin also offers to create devtool workspaces and run + ``devtool ide-sdk`` with a few mouse clicks. + Of course, issuing commands in the terminal works as well. + +- To work on the source code of a recipe another instance of VSCode is + started in the recipe's workspace. Example:: + + code build/workspace/sources/my-recipe + + This instance of VSCode uses plugins that are useful for the development + of the application. ``devtool ide-sdk`` generates the necessary + ``extensions.json``, ``settings.json``, ``tasks.json`` and ``launch.json`` + configuration files for all the involved plugins. + + When the source code folder present in the workspace folder is opened in + VSCode for the first time, a pop-up message recommends installing the + required plugins. + After accepting the installation of the plugins, working with the source + code or some debugging tasks should work as usual with VSCode. + + Starting the VSCode instances in the recipe workspace folders can also be + done by a mouse click on the recipe workspaces in the first VSCode + instance. + +- 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. + + For recipes inheriting :ref:`ref-classes-cmake-qemu` rather than + :ref:`ref-classes-cmake`, executing cross-compiled unit tests on the host + can be supported transparently with QEMU user-mode. + +- To work with Meson press ``Ctrl + Shift + p``, type ``meson``. This will + show some possible commands like compiling or executing the unit tests. + + A note on running cross-compiled unit tests on the host: Meson enables + support for QEMU user mode by default. It is expected that the execution + of the unit tests from the IDE will work without any additional steps, + given that the code is suitable for the execution on the host machine. + +- For C/C++ IntelliSense (code completion, navigation and diagnostics), + ``devtool ide-sdk`` configures either the ``clangd`` language server or + Microsoft's C/C++ extension (``cpptools``), matched to the recipe's real + cross-compiler via the generated ``compile_commands.json``. ``clangd`` + is used automatically for recipes built with the LLVM/clang toolchain; + other recipes default to ``cpptools``, but can opt into ``clangd`` too + by setting the recipe's ``IDE_SDK_INTELLISENSE`` variable to "clangd". + When ``clangd`` is used and the recipe's source tree contains a + ``.clang-format`` file, ``devtool ide-sdk`` also configures VSCode to + format C/C++ files with ``clangd`` on save, honoring that style file. + +- For the deployment to the target device, just press ``Ctrl + Shift + p``, + type ``task``. Select ``install && deploy-target``. This runs only + :ref:`ref-tasks-install` through BitBake, so that the build results + produced by the IDE are kept, and then deploys its output. + + By default, every file installed by the recipe is deployed (except + files that only end up in a ``-staticdev``, ``-dbg`` or ``-src`` + package, which are not useful on a live target). Use the ``--package`` + and/or ``--file-glob`` options of ``devtool ide-sdk`` (or + ``devtool deploy-target``) to deploy only a subset of the installed + files, for example ``--package my-recipe-tests`` or + ``--file-glob "/usr/bin/*"``. Both options may be given multiple times + and combined, and may be prefixed with ``RECIPE:`` (e.g. + ``--package "RECIPE:,-doc"``) to scope the option to one of several + recipes being processed by a single ``devtool ide-sdk`` invocation. + +- 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 session 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. + + VSCode supports GDB in many different setups and configurations for + many different use cases. However, most of these have limitations for + cross-development: they support only a few target architectures, or + require a high performance target device. ``devtool ide-sdk`` + therefore uses the classic, generic setup: GDB on the development host + and gdbserver on the target device. + + For recipes built with the LLVM/clang toolchain (:term:`TOOLCHAIN` set + to "clang"), ``devtool ide-sdk`` automatically uses LLDB and + ``lldb-server`` instead of GDB and ``gdbserver``, with no extra + command-line option needed. GDB and LLDB can be used side by side when + several recipes using different toolchains are processed by the same + ``devtool ide-sdk`` invocation. + + For a recipe whose binary is started by ``systemd`` or a SysV init + script (i.e. it runs as a persistent service rather than being started + directly by the debugger), an additional "Attach" debug configuration + is generated alongside the regular one. Selecting it attaches the + debugger to the already-running instance of the service on the target + instead of starting a new one. + + Roughly summarized, this means: + + - The binaries are copied via SSH to the remote target device by a + script referred by ``tasks.json``. + + - gdbserver is started on the remote target device via SSH by a script + referred by ``tasks.json``. + + Changing the parameters that are passed to the debugging executable + requires modifying the generated script. The script is located at + ``oe-scripts/gdbserver_*``. Defining the parameters in the ``args`` + field in the ``launch.json`` file does not work. + + - VSCode connects to gdbserver as documented in + `Remote debugging or debugging with a local debugger server + `__. + +Selecting the IDE +^^^^^^^^^^^^^^^^^ + +The ``--ide`` option selects the IDE plugin. It can be given multiple times +to configure several IDEs in one invocation, and ``--ide=all`` configures +every supported IDE:: + + $ devtool ide-sdk my-recipe core-image-minimal --ide=code --ide=none + $ devtool ide-sdk my-recipe core-image-minimal --ide=all + +Support for further IDEs is implemented as plugins, which optional layers +can provide as well. + +Debugging without an IDE +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Additionally ``--ide=none`` is supported. With the ``none`` IDE parameter, +some generic configuration files like ``gdbinit`` files and some helper +scripts starting gdbserver remotely on the target device as well as the GDB +client on the host are generated. + +Example: ``cmake-example`` walkthrough +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here is a usage example for the ``cmake-example`` recipe from the +``meta-selftest`` layer which inherits :ref:`ref-classes-cmake-qemu`: + +.. code-block:: sh + + # Create the SDK + devtool modify cmake-example --debug-build + devtool ide-sdk cmake-example core-image-minimal -c --ide=none + + # Install the firmware on a target device or start QEMU + runqemu + + # From exploring the workspace of cmake-example + cd build/workspace/sources/cmake-example + + # Find cmake-native and save the path into a variable + # Note: using just cmake instead of $CMAKE_NATIVE would work in many cases + CMAKE_NATIVE="$(jq -r '.configurePresets[0] | "\(.cmakeExecutable)"' CMakeUserPresets.json)" + + # List available CMake presets + "$CMAKE_NATIVE" --list-presets + Available configure presets: + + "cmake-example-cortexa57" - cmake-example: cortexa57 + + # Re-compile the already compiled sources + "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 + ninja: no work to do. + # Do a clean re-build + "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target clean + [1/1] Cleaning all built files... + Cleaning... 8 files. + "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target all + [7/7] Linking CXX executable cmake-example - This instance of VSCode uses plugins that are useful for the development - of the application. ``devtool ide-sdk`` generates the necessary - ``extensions.json``, ``settings.json``, ``tasks.json`` and ``launch.json`` - configuration files for all the involved plugins. - - When the source code folder present in the workspace folder is opened in - VSCode for the first time, a pop-up message recommends installing the - required plugins. - After accepting the installation of the plugins, working with the source - code or some debugging tasks should work as usual with VSCode. - - Starting the VSCode instances in the recipe workspace folders can also be - done by a mouse click on the recipe workspaces in the first VSCode - instance. - - - 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. - - For recipes inheriting :ref:`ref-classes-cmake-qemu` rather than - :ref:`ref-classes-cmake`, executing cross-compiled unit tests on the host - can be supported transparently with QEMU user-mode. - - - To work with Meson press ``Ctrl + Shift + p``, type ``meson``. This will - show some possible commands like compiling or executing the unit tests. - - A note on running cross-compiled unit tests on the host: Meson enables - support for QEMU user mode by default. It is expected that the execution - of the unit tests from the IDE will work without any additional steps, - given that the code is suitable for the execution on the host machine. + # Run the cross-compiled unit tests with QEMU user-mode + "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target test + [0/1] Running tests... + Test project .../build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 + Start 1: test-cmake-example + 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec - - For the deployment to the target device, just press ``Ctrl + Shift + p``, - type ``task``. Select ``install && deploy-target``. + 100% tests passed, 0 tests failed out of 1 - - 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. + Total Test time (real) = 0.03 sec - Starting a remote debugging session 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. + # Using CTest directly is possible as well + CTEST_NATIVE="$(dirname "$CMAKE_NATIVE")/ctest" - VSCode supports GDB with many different setups and configurations for - many different use cases. However, most of these setups have some - limitations when it comes to cross-development, support only a few target - architectures or require a high performance target device. Therefore - ``devtool ide-sdk`` supports the classic, generic setup with GDB on the - development host and gdbserver on the target device. - - Roughly summarized, this means: - - - The binaries are copied via SSH to the remote target device by a - script referred by ``tasks.json``. + # List available CMake presets + "$CTEST_NATIVE" --list-presets + Available test presets: - - gdbserver is started on the remote target device via SSH by a script - referred by ``tasks.json``. + "cmake-example-cortexa57" - cmake-example: cortexa57 - Changing the parameters that are passed to the debugging executable - requires modifying the generated script. The script is located at - ``oe-scripts/gdbserver_*``. Defining the parameters in the ``args`` - field in the ``launch.json`` file does not work. + # Run the cross-compiled unit tests with QEMU user-mode + "$CTEST_NATIVE" --preset "cmake-example-cortexa57" + Test project ...build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 + Start 1: test-cmake-example + 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec - - VSCode connects to gdbserver as documented in - `Remote debugging or debugging with a local debugger server - `__. - - Additionally ``--ide=none`` is supported. With the ``none`` IDE parameter, - some generic configuration files like ``gdbinit`` files and some helper - scripts starting gdbserver remotely on the target device as well as the GDB - client on the host are generated. + 100% tests passed, 0 tests failed out of 1 - Here is a usage example for the ``cmake-example`` recipe from the - ``meta-selftest`` layer which inherits :ref:`ref-classes-cmake-qemu`: + Total Test time (real) = 0.03 sec - .. code-block:: sh + # Deploying the new build to the target device (default is QEUM at 192.168.7.2) + oe-scripts/install_and_deploy_cmake-example-cortexa57 - # Create the SDK - devtool modify cmake-example --debug-build - devtool ide-sdk cmake-example core-image-minimal -c --ide=none + # Start a remote debugging session with gdbserver on the target and GDB on the host + oe-scripts/gdbserver_1234_usr-bin-cmake-example_m + oe-scripts/gdb_1234_usr-bin-cmake-example + break main + run + step + stepi + continue + quit - # Install the firmware on a target device or start QEMU - runqemu + # Stop gdbserver on the target device + oe-scripts/gdbserver_1234_usr-bin-cmake-example_m stop - # From exploring the workspace of cmake-example - cd build/workspace/sources/cmake-example +Shared sysroots mode +-------------------- - # Find cmake-native and save the path into a variable - # Note: using just cmake instead of $CMAKE_NATIVE would work in many cases - CMAKE_NATIVE="$(jq -r '.configurePresets[0] | "\(.cmakeExecutable)"' CMakeUserPresets.json)" +Concept +^^^^^^^ - # List available CMake presets - "$CMAKE_NATIVE" --list-presets - Available configure presets: +For some recipes and use cases, modified mode's full ``devtool``/``bitbake`` +integration might not be suitable. To offer full feature parity with the +SDK and the eSDK instead, ``--mode=shared`` bootstraps an SDK directly +from the BitBake environment, offering the same Environment Setup script +as described in :ref:`running_the_ext_sdk_env`. The IDE is then configured +to use the shared :term:`Sysroots ` and tools from that SDK. +``devtool ide-sdk --mode=shared`` is basically a wrapper around the setup +of the extensible SDK as described in :ref:`setting_up_ext_sdk_in_build`. - "cmake-example-cortexa57" - cmake-example: cortexa57 +Shared mode can also be given an image recipe. The image is then built as +part of the SDK, and IDE plugins can use it to generate image-based +configurations, e.g. for debugging with the debug symbols and sources of the +image's ``rootfs-dbg``. As in modified mode, ``--nfs`` exports the image's +root filesystem (see +:ref:`dev-manual/devtool:booting the target from an nfs-exported root filesystem`), +which requires an image recipe:: - # Re-compile the already compiled sources - "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 - ninja: no work to do. - # Do a clean re-build - "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target clean - [1/1] Cleaning all built files... - Cleaning... 8 files. - "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target all - [7/7] Linking CXX executable cmake-example + $ devtool ide-sdk --mode=shared core-image-minimal --nfs=rootfs-dbg --target root@192.168.7.2 + +Example +^^^^^^^ - # Run the cross-compiled unit tests with QEMU user-mode - "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target test - [0/1] Running tests... - Test project .../build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 - Start 1: test-cmake-example - 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec +Creating an SDK with shared :term:`Sysroots ` that contains all the +dependencies needed to work with ``my-recipe`` is possible with the following +example command:: + + $ devtool ide-sdk --mode=shared my-recipe - 100% tests passed, 0 tests failed out of 1 +For VSCode the cross-toolchain is exposed as a CMake kit. CMake kits are +defined in ``~/.local/share/CMakeTools/cmake-tools-kits.json``. +The following example shows how the cross-toolchain can be selected in +VSCode. First of all we need a folder containing a CMake project. +For this example, let's create a CMake project and start VSCode:: + + 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`` - Total Test time (real) = 0.03 sec +Finally most of the features provided by CMake and the IDE should be +available. - # Using CTest directly is possible as well - CTEST_NATIVE="$(dirname "$CMAKE_NATIVE")/ctest" +Other IDEs than VSCode are supported as well. However, +``devtool ide-sdk --mode=shared --ide=none my-recipe`` is currently +just a simple wrapper for the setup of the extensible SDK, as described in +:ref:`setting_up_ext_sdk_in_build`. - # List available CMake presets - "$CTEST_NATIVE" --list-presets - Available test presets: +Combining modified and shared mode +---------------------------------- - "cmake-example-cortexa57" - cmake-example: cortexa57 +Modified mode configures the IDE for recipes in ``devtool modify`` state, +while shared mode provides a standalone cross-toolchain and shared +:term:`Sysroots ` for working on other source code. Repeating the +``--mode`` option runs both workflows in a single invocation, so the image +is built only once:: - # Run the cross-compiled unit tests with QEMU user-mode - "$CTEST_NATIVE" --preset "cmake-example-cortexa57" - Test project ...build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 - Start 1: test-cmake-example - 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec + $ devtool modify my-recipe + $ devtool ide-sdk --mode=modified --mode=shared my-recipe other-recipe core-image-minimal - 100% tests passed, 0 tests failed out of 1 +In this example: - Total Test time (real) = 0.03 sec - - # Deploying the new build to the target device (default is QEUM at 192.168.7.2) - oe-scripts/install_and_deploy_cmake-example-cortexa57 - - # Start a remote debugging session with gdbserver on the target and GDB on the host - oe-scripts/gdbserver_1234_usr-bin-cmake-example_m - oe-scripts/gdb_1234_usr-bin-cmake-example - break main - run - step - stepi - continue - quit - - # Stop gdbserver on the target device - oe-scripts/gdbserver_1234_usr-bin-cmake-example_m stop - -#. *Shared sysroots mode* - - Creating an SDK with shared :term:`Sysroots ` that contains all the - dependencies needed to work with ``my-recipe`` is possible with the following - example command:: - - $ devtool ide-sdk --mode=shared my-recipe - - For VSCode the cross-toolchain is exposed as a CMake kit. CMake kits are - defined in ``~/.local/share/CMakeTools/cmake-tools-kits.json``. - The following example shows how the cross-toolchain can be selected in - VSCode. First of all we need a folder containing a CMake project. - For this example, let's create a CMake project and start VSCode:: - - 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`` - - Finally most of the features provided by CMake and the IDE should be - available. - - Other IDEs than VSCode are supported as well. However, - ``devtool ide-sdk --mode=shared --ide=none my-recipe`` is currently - just a simple wrapper for the setup of the extensible SDK, as described in - :ref:`setting_up_ext_sdk_in_build`. +- ``my-recipe`` is in ``devtool modify`` state and gets its recipe-specific + IDE configuration in its workspace, as described in + :ref:`dev-manual/devtool:modified mode`. + +- ``other-recipe`` is not modified. It is added to the shared sysroots, + which provide the environment setup script to build other source code with + the cross-toolchain, as described in + :ref:`dev-manual/devtool:shared sysroots mode`. + +- ``core-image-minimal`` provides the root filesystem for the remote + debugging of both. Its ``rootfs-dbg`` provides the debug symbols and + sources, and ``--nfs`` can export its root filesystem for the target. + +Without ``--mode=modified`` in the invocation, modified recipes are rejected, +and without ``--mode=shared`` in the invocation, recipes that are not +modified are rejected. If ``--mode`` is omitted, modified mode is used. Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software ======================================================================================================= @@ -895,6 +1235,9 @@ The following diagram shows the common development flow used with the $ devtool deploy-target recipe target The target is a live target machine running as an SSH server. + Alternatively, ``target`` can be an absolute path to a local + pseudo-managed rootfs directory, in which case the files are copied + into it directly, without SSH. You can, of course, also deploy the image you build using the ``devtool build-image`` command to actual hardware. However, diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst index d2e80611a..13319beda 100644 --- a/documentation/ref-manual/devtool-reference.rst +++ b/documentation/ref-manual/devtool-reference.rst @@ -681,6 +681,9 @@ of SDKs are generated: - ``shared`` mode: this creates a cross-compiling toolchain and the corresponding shared sysroot directories of the supplied recipe(s). +The ``--mode`` option can be repeated to combine both modes, for example +``--mode=modified --mode=shared``. + The ``--target`` option can be used to specify a ``username@hostname`` string and create a remote debugging configuration for the recipe. Similarly to ``devtool deploy-target``, it requires an SSH server running on the target. From patchwork Thu Oct 15 20:06:34 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: AdrianF X-Patchwork-Id: 100913 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6289ECCA469 for ; Thu, 15 Oct 2026 20:08:06 +0000 (UTC) Received: from mta-64-227.siemens.flowmailer.net (mta-64-227.siemens.flowmailer.net [185.136.64.227]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.6599.1792094877886050169 for ; Thu, 15 Oct 2026 13:07:59 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=adrian.freihofer@siemens.com header.s=fm2 header.b=MHcVh4Ch; spf=pass (domain: rts-flowmailer.siemens.com, ip: 185.136.64.227, mailfrom: fm-1329275-202610152007552efeed1d290002070f-0ttakw@rts-flowmailer.siemens.com) Received: by mta-64-227.siemens.flowmailer.net with ESMTPSA id 202610152007552efeed1d290002070f for ; Thu, 15 Oct 2026 22:07:55 +0200 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; s=fm2; d=siemens.com; i=adrian.freihofer@siemens.com; h=Date:From:Subject:To:Message-ID:MIME-Version:Content-Type:Content-Transfer-Encoding:Cc:References:In-Reply-To; bh=G+JE/nb/nkV9WFL60/SIp6atBMW19mxq1K2bXds6JpI=; b=MHcVh4ChBhMtIBxmfKxLWyIHelSrQpMgVmP4z89GyMY2ER9oJgy+4+JkJoNbmCiVOU4vg0 1hB6oKtKSKLExCoLOTCq2DvFXpAXOK9atrUotrMp9aKstXMB2xLFyw1ulfIJR+gX84DjwyV1 zomyPFfzke6HcSaROgiijxotpTG6dJJ/KF+dzQf5wgalTZG0MdRSg6rrn79+57jhj3CqbESO I7jqxqQPyFWia38QyrdcUwdznDZE+t8v0HHRcU4RCUskvhjFyhDWN+2kZFuuW7t6dk/Bx8D+ 4E8K65dAdgcrnC8oQnZQRkAD8rtebqEo8E1nAk/t+TKdNBcI4ZE7BZ9A==; From: AdrianF To: docs@lists.yoctoproject.org Cc: Adrian Freihofer Subject: [PATCH v3 3/4] dev-manual/devtool: add diagrams for the ide-sdk workflow and architecture Date: Thu, 15 Oct 2026 22:06:34 +0200 Message-ID: <20261015200726.2391599-4-adrian.freihofer@siemens.com> In-Reply-To: <20261015200726.2391599-1-adrian.freihofer@siemens.com> References: <20261015200726.2391599-1-adrian.freihofer@siemens.com> MIME-Version: 1.0 X-Flowmailer-Platform: Siemens Feedback-ID: 519:519-1329275:519-21489:flowmailer List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 15 Oct 2026 20:08:06 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10688 From: Adrian Freihofer Add three diagrams to the devtool ide-sdk section: a typical usage workflow, the architecture of the SDK/IDE relationship, and a variant of the architecture for the --nfs=rootfs-dbg mode. The diagrams are Mermaid (.mmd) flowcharts, kept as the maintainable source next to the pre-rendered SVGs that the documentation includes, so building the documentation needs no Mermaid tooling. The command to regenerate an SVG is documented at the top of each .mmd file. The Mermaid configuration in each .mmd follows the documentation SVG policy (GNOME HIG colors, Nimbus Roman 10pt text, rounded boxes, no shadows). Colors: blue for the SDK/build environment, purple for devtool-managed workspace/NFS directories, brown for the target device, orange for entry-point commands and green for editable/source elements. The images are scaled with the page width but never beyond their natural size, which is what the new max-natural-size CSS class is for. The text then stays at the intended size. Signed-off-by: Adrian Freihofer --- documentation/dev-manual/devtool.rst | 27 +++++- .../figures/devtool-ide-sdk-architecture.mmd | 84 +++++++++++++++++ .../figures/devtool-ide-sdk-architecture.svg | 1 + .../devtool-ide-sdk-nfs-architecture.mmd | 89 +++++++++++++++++++ .../devtool-ide-sdk-nfs-architecture.svg | 1 + .../figures/devtool-ide-sdk-workflow.mmd | 74 +++++++++++++++ .../figures/devtool-ide-sdk-workflow.svg | 1 + .../sphinx-static/theme_overrides.css | 5 ++ 8 files changed, 279 insertions(+), 3 deletions(-) create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-architecture.mmd create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-architecture.svg create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.mmd create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.svg create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-workflow.mmd create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-workflow.svg diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst index e182b427b..ba0435a46 100644 --- a/documentation/dev-manual/devtool.rst +++ b/documentation/dev-manual/devtool.rst @@ -480,7 +480,14 @@ directly in the IDE, independently of ``devtool ide-sdk`` and without calling configuration that points the IDE directly at the build tool, the cross-toolchain and the debugger provided by the SDK. ``devtool ide-sdk`` only needs to be re-run later on, e.g. if a recipe's dependencies or its -build configuration change. +build configuration change: + +.. image:: figures/devtool-ide-sdk-workflow.svg + :width: 100% + :align: center + :class: max-natural-size + +.. centered:: Typical ``devtool ide-sdk`` use case Let's now take a closer look at how ``devtool ide-sdk`` and the generated IDE configuration make use of a regular ``bitbake`` environment as a SDK to @@ -541,7 +548,14 @@ The same architecture also allows the IDE to be configured to use further tools beyond the build tool, cross-compiler and debugger, e.g. ``clang-tidy``: any such tool just needs to be added as a native tool in ``recipe-sysroot-native``, in the Yocto reproducible way, for -``devtool ide-sdk`` to be able to point the IDE at it. +``devtool ide-sdk`` to be able to point the IDE at it: + +.. image:: figures/devtool-ide-sdk-architecture.svg + :width: 100% + :align: center + :class: max-natural-size + +.. centered:: Architecture of ``devtool ide-sdk`` To summarize the design described above, for supported build systems modified mode brings two key benefits: @@ -713,7 +727,14 @@ This changes the relationship between the SDK, the target device and the debug symbols compared to the architecture described above: instead of a separate ``rootfs`` booted by the target and a ``rootfs-dbg`` only consulted by the debugger on the host, both the target and the debugger -now use the same NFS-exported ``rootfs-dbg``. +now use the same NFS-exported ``rootfs-dbg``: + +.. image:: figures/devtool-ide-sdk-nfs-architecture.svg + :width: 100% + :align: center + :class: max-natural-size + +.. centered:: Architecture of ``devtool ide-sdk --nfs=rootfs-dbg`` Use ``--nfs-extract-dir=DIR`` to extract below ``DIR//`` instead of the default location in the workspace, for example when the NFS diff --git a/documentation/dev-manual/figures/devtool-ide-sdk-architecture.mmd b/documentation/dev-manual/figures/devtool-ide-sdk-architecture.mmd new file mode 100644 index 000000000..2bbff25c4 --- /dev/null +++ b/documentation/dev-manual/figures/devtool-ide-sdk-architecture.mmd @@ -0,0 +1,84 @@ +--- +config: + theme: base + look: classic + htmlLabels: false + fontFamily: '"Nimbus Roman", "Times New Roman", Times, serif' + fontSize: 13.33 + themeVariables: + primaryColor: "#99c1f1" + primaryBorderColor: "#62a0ea" + primaryTextColor: "#000000" + lineColor: "#000000" + edgeLabelBackground: "#ffffff" + clusterBkg: "#f6f5f4" + clusterBorder: "#c0bfbc" + titleColor: "#000000" + fontSize: 13.33px + themeCSS: | + .cluster-label tspan { font-weight: bold; } + rect { rx: 7.5px; ry: 7.5px; } + flowchart: + htmlLabels: false + useMaxWidth: false + curve: basis + padding: 10 + nodeSpacing: 23 + rankSpacing: 37 + wrappingWidth: 300 +--- +%% Regenerate: npx -y @mermaid-js/mermaid-cli -b transparent -i devtool-ide-sdk-architecture.mmd -o devtool-ide-sdk-architecture.svg +%% && sed -i 's/(bitbake tinfoil client)"] + ideconfig[["IDE configuration
(e.g. build tool preset,
debugger launch config)"]] + ide["IDE (e.g. VSCode)"] + srcdir[["S = e.g. workspace/sources/<recipe>
(source code, extracted by
devtool modify, edited in the IDE)"]] + + subgraph sdk["SDK (regular bitbake environment)"] + subgraph recipe_workdir["Recipe WORKDIR(s)"] + native_sysroot[["recipe-sysroot-native
build tool (e.g. CMake)
cross-compiler (e.g. <arch>-gcc)
debugger (e.g. gdb)
more tools..."]] + builddir[["B (build directory)
build artifacts)"]] + sysroot[["recipe-sysroot
(target headers & libs)"]] + destdir[["D = image
(non-stripped, relocated rpath,
managed by pseudo)"]] + end + + subgraph image_workdir["Image WORKDIR"] + rootfsdbg[["rootfs-dbg
(debug symbols of other
recipes' shared libraries)"]] + rootfs[["rootfs
(target root filesystem)"]] + end + end + + subgraph target["Target device"] + appbin["Application binary
(running)"] + debugserver["debug-server
(e.g. gdbserver)"] + end + + idesdk -->|generates| ideconfig + idesdk -->|"generates the SDK (via bitbake)"| sdk + ideconfig --> ide + ideconfig --> native_sysroot + ide -->|"calls directly, no bitbake needed"| native_sysroot + ide -->|"edit source"| srcdir + native_sysroot -->|"reads source from"| srcdir + native_sysroot -->|"builds in"| builddir + native_sysroot -.->|"--sysroot"| sysroot + builddir -->|install| destdir + destdir -->|"deploy (--strip)"| appbin + native_sysroot -->|"debug symbols:
unstripped binary"| destdir + native_sysroot -->|"debug symbols:
shared libraries"| rootfsdbg + native_sysroot -->|"remote debug
protocol"| debugserver + debugserver -->|"attach / run"| appbin + rootfs -->|"installed on target"| target + + style sdk fill:#f6f5f4,stroke:#3584e4,stroke-width:1px + style recipe_workdir fill:#ffffff,stroke:#62a0ea,stroke-width:1px + style image_workdir fill:#ffffff,stroke:#57e389,stroke-width:1px + style target fill:#f6f5f4,stroke:#b5835a,stroke-width:1px + + classDef orange fill:#ffbe6f,stroke:#ffa348,stroke-width:1px,color:#000000; + classDef green fill:#8ff0a4,stroke:#57e389,stroke-width:1px,color:#000000; + classDef default fill:#99c1f1,stroke:#62a0ea,stroke-width:1px,color:#000000; + class idesdk orange; + class srcdir green; diff --git a/documentation/dev-manual/figures/devtool-ide-sdk-architecture.svg b/documentation/dev-manual/figures/devtool-ide-sdk-architecture.svg new file mode 100644 index 000000000..44b7bf5fb --- /dev/null +++ b/documentation/dev-manual/figures/devtool-ide-sdk-architecture.svg @@ -0,0 +1 @@ +Target deviceSDK (regular bitbake environment)Image WORKDIRRecipe WORKDIR(s)generatesgenerates the SDK (via bitbake)calls directly, no bitbake needededit sourcereads source frombuilds in--sysrootinstalldeploy (--strip)debug symbols:unstripped binarydebug symbols:shared librariesremote debugprotocolattach / runinstalled on targetdevtool ide-sdk(bitbake tinfoil client)IDE configuration(e.g. build tool preset,debugger launch config)IDE (e.g. VSCode)S = e.g. workspace/sources/<recipe>(source code, extracted bydevtool modify, edited in the IDE)recipe-sysroot-nativebuild tool (e.g. CMake)cross-compiler (e.g. <arch>-gcc)debugger (e.g. gdb)more tools...B (build directory)build artifacts)recipe-sysroot(target headers & libs)D = image(non-stripped, relocated rpath,managed by pseudo)rootfs-dbg(debug symbols of otherrecipes' shared libraries)rootfs(target root filesystem)Application binary(running)debug-server(e.g. gdbserver) \ No newline at end of file diff --git a/documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.mmd b/documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.mmd new file mode 100644 index 000000000..0ec733a2e --- /dev/null +++ b/documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.mmd @@ -0,0 +1,89 @@ +--- +config: + theme: base + look: classic + htmlLabels: false + fontFamily: '"Nimbus Roman", "Times New Roman", Times, serif' + fontSize: 13.33 + themeVariables: + primaryColor: "#99c1f1" + primaryBorderColor: "#62a0ea" + primaryTextColor: "#000000" + lineColor: "#000000" + edgeLabelBackground: "#ffffff" + clusterBkg: "#f6f5f4" + clusterBorder: "#c0bfbc" + titleColor: "#000000" + fontSize: 13.33px + themeCSS: | + .cluster-label tspan { font-weight: bold; } + rect { rx: 7.5px; ry: 7.5px; } + flowchart: + htmlLabels: false + useMaxWidth: false + curve: basis + padding: 10 + nodeSpacing: 23 + rankSpacing: 37 + wrappingWidth: 300 +--- +%% Regenerate: npx -y @mermaid-js/mermaid-cli -b transparent -i devtool-ide-sdk-nfs-architecture.mmd -o devtool-ide-sdk-nfs-architecture.svg +%% && sed -i 's/(bitbake tinfoil client)"] + ideconfig[["IDE configuration
(e.g. build tool preset,
debugger launch config)"]] + ide["IDE (e.g. VSCode)"] + srcdir[["S = e.g. workspace/sources/<recipe>
(source code, extracted by
devtool modify, edited in the IDE)"]] + + subgraph sdk["SDK (regular bitbake environment)"] + subgraph recipe_workdir["Recipe WORKDIR(s)"] + native_sysroot[["recipe-sysroot-native
build tool (e.g. CMake)
cross-compiler (e.g. <arch>-gcc)
debugger (e.g. gdb)"]] + builddir[["B (build directory)
build artifacts)"]] + sysroot[["recipe-sysroot
(target headers & libs)"]] + destdir[["D = image
(non-stripped, relocated rpath,
managed by pseudo)"]] + end + + subgraph image_workdir["Image WORKDIR"] + rootfsdbg_src[["rootfs-dbg
(stripped binaries + debug symbols
of every recipe, combined by
image-combined-dbg)"]] + end + end + + subgraph nfs["NFS export"] + rootfsdbg[["<workspace>/nfs-exports/<image-recipe>/rootfs-dbg
(copy, kept in sync by devtool
deploy-target; persists across
debug sessions)"]] + end + + subgraph target["Target device"] + appbin["Application binary
(running)"] + debugserver["debug-server
(e.g. gdbserver)"] + end + + idesdk -->|generates| ideconfig + idesdk -->|"generates the SDK (via bitbake)"| sdk + rootfsdbg_src -->|"deployed, extracted
(--nfs=rootfs-dbg)"| rootfsdbg + ideconfig --> ide + ideconfig --> native_sysroot + ide -->|"calls directly, no bitbake needed"| native_sysroot + ide -->|"edit source"| srcdir + native_sysroot -->|"reads source from"| srcdir + native_sysroot -->|"builds in"| builddir + native_sysroot -.->|"--sysroot"| sysroot + builddir -->|install| destdir + destdir -->|"devtool deploy-target
(direct write, no SSH)"| rootfsdbg + native_sysroot -->|"debug symbols:
unstripped binary"| destdir + native_sysroot -->|"debug symbols:
other recipes'
shared libraries"| rootfsdbg + native_sysroot -->|"remote debug
protocol"| debugserver + debugserver -->|"attach / run"| appbin + target -->|"booted from
(NFS-mounted
root filesystem)"| rootfsdbg + + style sdk fill:#f6f5f4,stroke:#3584e4,stroke-width:1px + style recipe_workdir fill:#ffffff,stroke:#62a0ea,stroke-width:1px + style image_workdir fill:#ffffff,stroke:#57e389,stroke-width:1px + style nfs fill:#f6f5f4,stroke:#c061cb,stroke-width:1px + style target fill:#f6f5f4,stroke:#b5835a,stroke-width:1px + + classDef orange fill:#ffbe6f,stroke:#ffa348,stroke-width:1px,color:#000000; + classDef green fill:#8ff0a4,stroke:#57e389,stroke-width:1px,color:#000000; + classDef default fill:#99c1f1,stroke:#62a0ea,stroke-width:1px,color:#000000; + class idesdk orange; + class srcdir,rootfsdbg green; diff --git a/documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.svg b/documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.svg new file mode 100644 index 000000000..5d2cb1d30 --- /dev/null +++ b/documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.svg @@ -0,0 +1 @@ +Target deviceNFS exportSDK (regular bitbake environment)Image WORKDIRRecipe WORKDIR(s)generatesgenerates the SDK (via bitbake)deployed, extracted(--nfs=rootfs-dbg)calls directly, no bitbake needededit sourcereads source frombuilds in--sysrootinstalldevtool deploy-target(direct write, no SSH)debug symbols:unstripped binarydebug symbols:other recipes'shared librariesremote debugprotocolattach / runbooted from(NFS-mountedroot filesystem)devtool ide-sdk --nfs=rootfs-dbg(bitbake tinfoil client)IDE configuration(e.g. build tool preset,debugger launch config)IDE (e.g. VSCode)S = e.g. workspace/sources/<recipe>(source code, extracted bydevtool modify, edited in the IDE)recipe-sysroot-nativebuild tool (e.g. CMake)cross-compiler (e.g. <arch>-gcc)debugger (e.g. gdb)B (build directory)build artifacts)recipe-sysroot(target headers & libs)D = image(non-stripped, relocated rpath,managed by pseudo)rootfs-dbg(stripped binaries + debug symbolsof every recipe, combined byimage-combined-dbg)<workspace>/nfs-exports/<image-recipe>/rootfs-dbg(copy, kept in sync by devtooldeploy-target; persists acrossdebug sessions)Application binary(running)debug-server(e.g. gdbserver) \ No newline at end of file diff --git a/documentation/dev-manual/figures/devtool-ide-sdk-workflow.mmd b/documentation/dev-manual/figures/devtool-ide-sdk-workflow.mmd new file mode 100644 index 000000000..7584dcbb3 --- /dev/null +++ b/documentation/dev-manual/figures/devtool-ide-sdk-workflow.mmd @@ -0,0 +1,74 @@ +--- +config: + theme: base + look: classic + htmlLabels: false + fontFamily: '"Nimbus Roman", "Times New Roman", Times, serif' + fontSize: 13.33 + themeVariables: + primaryColor: "#99c1f1" + primaryBorderColor: "#62a0ea" + primaryTextColor: "#000000" + lineColor: "#000000" + edgeLabelBackground: "#ffffff" + clusterBkg: "#f6f5f4" + clusterBorder: "#c0bfbc" + titleColor: "#000000" + fontSize: 13.33px + themeCSS: | + .cluster-label tspan { font-weight: bold; } + rect { rx: 7.5px; ry: 7.5px; } + flowchart: + htmlLabels: false + useMaxWidth: false + curve: basis + padding: 10 + nodeSpacing: 23 + rankSpacing: 37 + wrappingWidth: 270 +--- +%% Regenerate: npx -y @mermaid-js/mermaid-cli -b transparent -i devtool-ide-sdk-workflow.mmd -o devtool-ide-sdk-workflow.svg +%% && sed -i 's/(extracted here)"]] + end + + gensdk["devtool ide-sdk recipe image
(generate SDK + IDE config)"] + + subgraph loop["Edit/build/debug loop"] + edit["Edit source code"] + build["Build
(build tool called
directly by the IDE)"] + deploy["Deploy to target"] + debug["Debug remotely
(e.g. GDB/LLDB + gdbserver/lldb-server)"] + end + + finish["devtool finish recipe layer
(turn changes into patches)"] + rerun_note>"rerun only if recipe
deps/config change"] + + modify --> ws_appends + modify -->|extracts| ws_src + ws_appends --> gensdk + ws_src --> gensdk + gensdk -->|"one-time setup"| edit + edit --> build + build --> deploy + deploy --> debug + debug -->|repeat| edit + edit -.->|"when done"| finish + gensdk -.- rerun_note + + style workspace fill:#f6f5f4,stroke:#c061cb,stroke-width:1px + style loop fill:#f6f5f4,stroke:#57e389,stroke-width:1px + + classDef orange fill:#ffbe6f,stroke:#ffa348,stroke-width:1px,color:#000000; + classDef green fill:#8ff0a4,stroke:#57e389,stroke-width:1px,color:#000000; + classDef note fill:#f6f5f4,stroke:#c0bfbc,stroke-width:1px,color:#5e5c64; + classDef default fill:#99c1f1,stroke:#62a0ea,stroke-width:1px,color:#000000; + class modify,gensdk,finish orange; + class ws_src,edit,build,deploy,debug green; + class rerun_note note; diff --git a/documentation/dev-manual/figures/devtool-ide-sdk-workflow.svg b/documentation/dev-manual/figures/devtool-ide-sdk-workflow.svg new file mode 100644 index 000000000..389b64a6b --- /dev/null +++ b/documentation/dev-manual/figures/devtool-ide-sdk-workflow.svg @@ -0,0 +1 @@ +Edit/build/debug loopdevtool workspaceextractsone-time setuprepeatwhen donedevtool modify recipe --debug-buildappends/recipe.bbappendsources/recipe(extracted here)devtool ide-sdk recipe image(generate SDK + IDE config)Edit source codeBuild(build tool calleddirectly by the IDE)Deploy to targetDebug remotely(e.g. GDB/LLDB + gdbserver/lldb-server)devtool finish recipe layer(turn changes into patches)rerun only if recipedeps/config change \ No newline at end of file diff --git a/documentation/sphinx-static/theme_overrides.css b/documentation/sphinx-static/theme_overrides.css index f9e067239..9c4b23f06 100644 --- a/documentation/sphinx-static/theme_overrides.css +++ b/documentation/sphinx-static/theme_overrides.css @@ -96,6 +96,11 @@ em { color: #444; } +/* Scale with the page, but never beyond the size the text is meant for */ +img.max-natural-size { + max-width: max-content; +} + [alt='Permalink'] { color: #eee; } [alt='Permalink']:hover { color: black; }