From patchwork Tue Oct 20 08:43:39 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: AdrianF X-Patchwork-Id: 101365 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.2847.1792485847520821550 for ; Tue, 20 Oct 2026 01:44:10 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=adrian.freihofer@siemens.com header.s=fm2 header.b=I5Kg3TqN; spf=pass (domain: rts-flowmailer.siemens.com, ip: 185.136.64.227, mailfrom: fm-1329275-202610200844030e4cb2b29e00020742-4b_e5d@rts-flowmailer.siemens.com) Received: by mta-64-227.siemens.flowmailer.net with ESMTPSA id 202610200844030e4cb2b29e00020742 for ; Tue, 20 Oct 2026 10:44:04 +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=Ab3JCK5Z7FtDnLkDEvAGb2IvNNQi940f7QrP5KV3yLg=; b=I5Kg3TqNnSdPtaLk8kINChlgpLFRzCnBkd+g16GhHP1MbvigRBDvTlNvhBvtY1CH0M/2Cc g+7yw0C/5ERDpIWB3gpgD2Kf7XxD0oqdcfYWvTk4QmbbbjnLQs1zYvZfOtmSZ55vjZMAiWSO GcOFe9NRJ877W/65uphdFj98tfwjmjG++LXfgH6J/Pk283UTtffglM1P5D2MZmfKHs731aEx Q9TUWAV+WCB/qWaaZiKKe+2P+cjVE2MHHOOSnRlm9o+lJsSkt1nv/Mp39pTb/NcLPYKqU7Xe G/wZ8lJQ0ROKncdF2eh+quTPqun6BJJgn9TB8yrMqB9aRTPM7XaRnmLw==; From: AdrianF To: docs@lists.yoctoproject.org Cc: Adrian Freihofer Subject: [PATCH v4 3/4] dev-manual/devtool: add diagrams for the ide-sdk workflow and architecture Date: Tue, 20 Oct 2026 10:43:39 +0200 Message-ID: <20261020084359.354498-4-adrian.freihofer@siemens.com> In-Reply-To: <20261020084359.354498-1-adrian.freihofer@siemens.com> References: <20261020084359.354498-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 lin-tor-korg-lkml-alma10-1 with HTTPS for ; Tue, 20 Oct 2026 08:44:19 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10696 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 Sans 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 | 76 ++++++++++++++++ .../figures/devtool-ide-sdk-workflow.svg | 1 + .../sphinx-static/theme_overrides.css | 5 ++ 8 files changed, 281 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 3f716515f..15e7dbb73 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: + +.. figure:: figures/devtool-ide-sdk-workflow.* + :width: 100% + :align: center + :class: max-natural-size + + 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 @@ -542,7 +549,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: + +.. figure:: figures/devtool-ide-sdk-architecture.* + :width: 100% + :align: center + :class: max-natural-size + + Architecture of ``devtool ide-sdk`` To summarize the design described above, for supported build systems modified mode brings two key benefits: @@ -722,7 +736,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``: + +.. figure:: figures/devtool-ide-sdk-nfs-architecture.* + :width: 100% + :align: center + :class: max-natural-size + + Architecture of ``devtool ide-sdk --nfs=rootfs-dbg`` Use ``--nfs-extract-dir=DIR`` to extract below ``DIR//`` instead of the default location in the ``devtool`` workspace, for example when 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..4ba2e7e7a --- /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 Sans", Helvetica, Arial, sans-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..09ba0551c --- /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 artifactsrecipe-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..e6141cde5 --- /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 Sans", Helvetica, Arial, sans-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..fa2876a19 --- /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 artifactsrecipe-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 bydevtool deploy-target;persists across debug 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..b0a9c732c --- /dev/null +++ b/documentation/dev-manual/figures/devtool-ide-sdk-workflow.mmd @@ -0,0 +1,76 @@ +--- +config: + theme: base + look: classic + htmlLabels: false + fontFamily: '"Nimbus Sans", Helvetica, Arial, sans-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:#c0bfbc,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 purple fill:#dc8add,stroke:#c061cb,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,build,deploy,debug,finish orange; + class ws_src,edit green; + class ws_appends purple; + 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..a83d9ff7d --- /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 3912872e1..3823db820 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; }