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; }