[PATCH 0/5] Make the SDK section not specific to the eSDK

[PATCH 0/5] Make the SDK section not specific to the eSDK

[Antonin Godard]

While the content of the SDK section covers both the standard and the
extensible SDKs, the title only referred to the extensible SDK which is
confusing.

This series comes with other various patches to improve this section.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (5):
      sdk-manual/appendix-customizing-standard.rst: use code block for bitbake assignment
      sdk-manual/intro.rst: remove a confusing sentence
      sdk-manual/intro.rst: link to sysroot term
      sdk-manual: rename the section to remove "extensible"
      sdk-manual/intro.rst: detail differences between standard and extensible sysroots

 documentation/index.rst                            |  2 +-
 .../sdk-manual/appendix-customizing-standard.rst   | 11 ++++----
 documentation/sdk-manual/index.rst                 |  6 ++---
 documentation/sdk-manual/intro.rst                 | 31 +++++++++++++++-------
 4 files changed, 32 insertions(+), 18 deletions(-)
---
base-commit: 41dae3c3da3ada1745fc60228ff6269c64ee2361
change-id: 20260529-sdk-clarifications-9aab0fa9a60e

[PATCH 1/5] sdk-manual/appendix-customizing-standard.rst: use code block for bitbake assignment

[Antonin Godard]

Use a code block for the DISTRO_FEATURES assignment instead of how it
appears as regular text currently.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/sdk-manual/appendix-customizing-standard.rst | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/documentation/sdk-manual/appendix-customizing-standard.rst b/documentation/sdk-manual/appendix-customizing-standard.rst
index c619c15e4..90b73dc20 100644
--- a/documentation/sdk-manual/appendix-customizing-standard.rst
+++ b/documentation/sdk-manual/appendix-customizing-standard.rst
@@ -27,8 +27,9 @@ Adding API Documentation to the Standard SDK
 
 You can include API documentation as well as any other documentation
 provided by recipes with the standard SDK by adding "api-documentation"
-to the
-:term:`DISTRO_FEATURES`
-variable: DISTRO_FEATURES:append = " api-documentation" Setting this
-variable as shown here causes the OpenEmbedded build system to build the
-documentation and then include it in the standard SDK.
+to the :term:`DISTRO_FEATURES` variable::
+
+   DISTRO_FEATURES:append = " api-documentation"
+
+Setting this variable as shown here causes the OpenEmbedded build system to
+build the documentation and then include it in the standard SDK.

-- 
2.55.0

[PATCH 2/5] sdk-manual/intro.rst: remove a confusing sentence

[Antonin Godard]

I have a hard time understanding the meaning of this sentence at this
point in the manual. populate_sdk and populate_sdk_ext are best known as
tasks, so the meaning for them as "archives" is unclear.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/sdk-manual/intro.rst | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
index dd2902cc4..3e78219fc 100644
--- a/documentation/sdk-manual/intro.rst
+++ b/documentation/sdk-manual/intro.rst
@@ -35,9 +35,7 @@ destined to run on some target machine. SDKs are completely
 self-contained. The binaries are linked against their own copy of
 ``libc``, which results in no dependencies on the target system. To
 achieve this, the pointer to the dynamic loader is configured at install
-time since that path cannot be dynamically altered. This is the reason
-for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext``
-archives.
+time since that path cannot be dynamically altered.
 
 Another feature of the SDKs is that only one set of cross-compiler
 toolchain binaries are produced for any given architecture. This feature

-- 
2.55.0

[PATCH 3/5] sdk-manual/intro.rst: link to sysroot term

[Antonin Godard]

Link to the definition of a sysroot (from our glossary) when it is first
introduced and later in the "Sysroots" section.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/sdk-manual/intro.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
index 3e78219fc..53246bd9a 100644
--- a/documentation/sdk-manual/intro.rst
+++ b/documentation/sdk-manual/intro.rst
@@ -45,7 +45,7 @@ environment script and contained in variables such as
 :term:`CC` and
 :term:`LD`. This reduces the space needed
 for the tools. Understand, however, that every target still needs its own
-sysroot because those binaries are target-specific.
+:term:`sysroot` because those binaries are target-specific.
 
 The SDK development environment consists of the following:
 
@@ -117,7 +117,7 @@ cross-toolchain works with a matching target sysroot.
 Sysroots
 --------
 
-The native and target sysroots contain needed headers and libraries for
+The native and target :term:`sysroots <Sysroot>` contain needed headers and libraries for
 generating binaries that run on the target architecture. The target
 sysroot is based on the target root filesystem image that is built by
 the OpenEmbedded build system and uses the same metadata configuration

-- 
2.55.0

[PATCH 4/5] sdk-manual: rename the section to remove "extensible"

[Antonin Godard]

The SDK manual covers both the standard and extensible SDKs yet the
title does not imply that, so rename the section to "Yocto Project
Application Development and the Software Development Kit (SDK) Manual".

As a consequence, rename the first section title and reword the intro.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/index.rst            | 2 +-
 documentation/sdk-manual/index.rst | 6 +++---
 documentation/sdk-manual/intro.rst | 8 ++++----
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/documentation/index.rst b/documentation/index.rst
index afabb6615..d8603c2f5 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -67,7 +67,7 @@ infrastructure.
    Linux Kernel Development Manual <kernel-dev/index>
    Security Manual <security-manual/index>
    Profile and Tracing Manual <profile-manual/index>
-   Application Development and the Extensible SDK (eSDK) <sdk-manual/index>
+   Application Development and SDK Manual <sdk-manual/index>
    Toaster Manual <toaster-manual/index>
    Test Environment Manual <test-manual/index>
    BitBake User Manual <bitbake>
diff --git a/documentation/sdk-manual/index.rst b/documentation/sdk-manual/index.rst
index dc7186b91..477274ab9 100644
--- a/documentation/sdk-manual/index.rst
+++ b/documentation/sdk-manual/index.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
 
-========================================================================================
-Yocto Project Application Development and the Extensible Software Development Kit (eSDK)
-========================================================================================
+===================================================================================
+Yocto Project Application Development and the Software Development Kit (SDK) Manual
+===================================================================================
 
 |
 
diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
index 53246bd9a..8ccbcfa20 100644
--- a/documentation/sdk-manual/intro.rst
+++ b/documentation/sdk-manual/intro.rst
@@ -4,11 +4,11 @@
 Introduction
 ************
 
-eSDK Introduction
-=================
+SDK Introduction
+================
 
-Welcome to the Yocto Project Application Development and the Extensible
-Software Development Kit (eSDK) manual. This manual
+Welcome to the Yocto Project Application Development and the
+Software Development Kit (SDK) manual. This manual
 explains how to use both the Yocto Project extensible and standard
 SDKs to develop applications and images.
 

-- 
2.55.0

[PATCH 5/5] sdk-manual/intro.rst: detail differences between standard and extensible sysroots

[Antonin Godard]

The sysroot in the standard and the extensible SDKs are managed
differently. Detail this in the Sysroots section.

[YOCTO #14830]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/sdk-manual/intro.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
index 8ccbcfa20..2e5f73f0b 100644
--- a/documentation/sdk-manual/intro.rst
+++ b/documentation/sdk-manual/intro.rst
@@ -123,6 +123,21 @@ sysroot is based on the target root filesystem image that is built by
 the OpenEmbedded build system and uses the same metadata configuration
 used to build the cross-toolchain.
 
+However, the extensible and standard SDKs sysroot differ in content:
+
+-  The standard SDK sysroot only contains libraries and headers for the packages
+   found in the :term:`TOOLCHAIN_TARGET_TASK` and :term:`TOOLCHAIN_HOST_TASK`
+   definitions, for the target and native sysroots respectively.
+
+   See :doc:`/sdk-manual/appendix-customizing-standard` to learn how to
+   customize it.
+
+-  The extensible SDK sysroot is completely managed by the ``devtool``
+   command-line tool, and its content is the same as the sysroot of the image
+   recipe for which the SDK was built.
+
+   See :doc:`/sdk-manual/appendix-customizing` to learn how to customize it.
+
 The QEMU Emulator
 -----------------
 

-- 
2.55.0

Re: [docs] [PATCH 1/5] sdk-manual/appendix-customizing-standard.rst: use code block for bitbake assignment

[Quentin Schulz]

Hi Antonin,

On 7/29/26 12:02 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Use a code block for the DISTRO_FEATURES assignment instead of how it
> appears as regular text currently.
> 

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [docs] [PATCH 2/5] sdk-manual/intro.rst: remove a confusing sentence

[Quentin Schulz]

Hi Antonin,

On 7/29/26 12:02 PM, Antonin Godard via lists.yoctoproject.org wrote:
> I have a hard time understanding the meaning of this sentence at this
> point in the manual. populate_sdk and populate_sdk_ext are best known as
> tasks, so the meaning for them as "archives" is unclear.
> 

Same here. Going back in the history, the commit that introduced this in 
the docs isn't providing much more info, so I guess:

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [docs] [PATCH 3/5] sdk-manual/intro.rst: link to sysroot term

[Quentin Schulz]

Hi Antonin,

On 7/29/26 12:02 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Link to the definition of a sysroot (from our glossary) when it is first
> introduced and later in the "Sysroots" section.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/sdk-manual/intro.rst | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
> index 3e78219fc..53246bd9a 100644
> --- a/documentation/sdk-manual/intro.rst
> +++ b/documentation/sdk-manual/intro.rst
> @@ -45,7 +45,7 @@ environment script and contained in variables such as
>   :term:`CC` and
>   :term:`LD`. This reduces the space needed
>   for the tools. Understand, however, that every target still needs its own
> -sysroot because those binaries are target-specific.
> +:term:`sysroot` because those binaries are target-specific.
>   

We capitalized the Sysroot term, so maybe have it capitalized here as 
well (I don't think it makes a difference but at least is consistent :) ).

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [docs] [PATCH 4/5] sdk-manual: rename the section to remove "extensible"

[Quentin Schulz]

Hi Antonin,

On 7/29/26 12:02 PM, Antonin Godard via lists.yoctoproject.org wrote:
> The SDK manual covers both the standard and extensible SDKs yet the
> title does not imply that, so rename the section to "Yocto Project
> Application Development and the Software Development Kit (SDK) Manual".
> 

Well, now it's the opposite :)

> As a consequence, rename the first section title and reword the intro.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/index.rst            | 2 +-
>   documentation/sdk-manual/index.rst | 6 +++---
>   documentation/sdk-manual/intro.rst | 8 ++++----
>   3 files changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/documentation/index.rst b/documentation/index.rst
> index afabb6615..d8603c2f5 100644
> --- a/documentation/index.rst
> +++ b/documentation/index.rst
> @@ -67,7 +67,7 @@ infrastructure.
>      Linux Kernel Development Manual <kernel-dev/index>
>      Security Manual <security-manual/index>
>      Profile and Tracing Manual <profile-manual/index>
> -   Application Development and the Extensible SDK (eSDK) <sdk-manual/index>
> +   Application Development and SDK Manual <sdk-manual/index>
>      Toaster Manual <toaster-manual/index>
>      Test Environment Manual <test-manual/index>
>      BitBake User Manual <bitbake>
> diff --git a/documentation/sdk-manual/index.rst b/documentation/sdk-manual/index.rst
> index dc7186b91..477274ab9 100644
> --- a/documentation/sdk-manual/index.rst
> +++ b/documentation/sdk-manual/index.rst
> @@ -1,8 +1,8 @@
>   .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
>   
> -========================================================================================
> -Yocto Project Application Development and the Extensible Software Development Kit (eSDK)
> -========================================================================================
> +===================================================================================
> +Yocto Project Application Development and the Software Development Kit (SDK) Manual
> +===================================================================================
>   

Maybe "Software Development Kits (SDK/eSDK)"?

>   |
>   
> diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
> index 53246bd9a..8ccbcfa20 100644
> --- a/documentation/sdk-manual/intro.rst
> +++ b/documentation/sdk-manual/intro.rst
> @@ -4,11 +4,11 @@
>   Introduction
>   ************
>   
> -eSDK Introduction
> -=================
> +SDK Introduction

SDK/eSDK?

> +================
>   
> -Welcome to the Yocto Project Application Development and the Extensible
> -Software Development Kit (eSDK) manual. This manual
> +Welcome to the Yocto Project Application Development and the
> +Software Development Kit (SDK) manual. This manual

Ditto.

It's a bit confusing to use SDK as 'either "standard" SDK or eSDK' and 
also '"standard" SDK'. I don't have anything to suggest though :/

Cheers,
Quentin

Re: [docs] [PATCH 5/5] sdk-manual/intro.rst: detail differences between standard and extensible sysroots

[Quentin Schulz]

Hi Antonin,

On 7/29/26 12:02 PM, Antonin Godard via lists.yoctoproject.org wrote:
> The sysroot in the standard and the extensible SDKs are managed
> differently. Detail this in the Sysroots section.
> 
> [YOCTO #14830]
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/sdk-manual/intro.rst | 15 +++++++++++++++
>   1 file changed, 15 insertions(+)
> 
> diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
> index 8ccbcfa20..2e5f73f0b 100644
> --- a/documentation/sdk-manual/intro.rst
> +++ b/documentation/sdk-manual/intro.rst
> @@ -123,6 +123,21 @@ sysroot is based on the target root filesystem image that is built by
>   the OpenEmbedded build system and uses the same metadata configuration
>   used to build the cross-toolchain.
>   
> +However, the extensible and standard SDKs sysroot differ in content:
> +

Why did we stop referring to the Sysroot term (:term:`Sysroot`)?

> +-  The standard SDK sysroot only contains libraries and headers for the packages

s/for/of/?

I think we should also mention this brings the libraries and headers of 
their dependencies (recursively) as well?

> +   found in the :term:`TOOLCHAIN_TARGET_TASK` and :term:`TOOLCHAIN_HOST_TASK`
> +   definitions, for the target and native sysroots respectively.
> +

I know we have a nativesdk OVERRIDE, so is it still a native/target 
sysroot or should it be named nativesdk too (I've never built an SDK so 
I don't know).

> +   See :doc:`/sdk-manual/appendix-customizing-standard` to learn how to
> +   customize it.
> +
> +-  The extensible SDK sysroot is completely managed by the ``devtool``

Can we maybe point at some docs for devtool? From a quick grep, maybe 
something in documentation/ref-manual/devtool-reference.rst?

> +   command-line tool, and its content is the same as the sysroot of the image
> +   recipe for which the SDK was built.
> +

I guess we could show how to do this here?

I think it should be something like:

bitbake my-image -c populate_sdk

(or maybe point at 
https://docs.yoctoproject.org/sdk-manual/appendix-obtain.html#building-an-sdk-installer 
?).

> +   See :doc:`/sdk-manual/appendix-customizing` to learn how to customize it.
> +

Thinking about it, we probably should update 
documentation/ref-manual/terms.rst for the Sysroot entry in the glossary 
to explain sysroot for the SDKs (or at the very least point at the 
section here).

Cheers,
Quentin

Re: [docs] [PATCH 5/5] sdk-manual/intro.rst: detail differences between standard and extensible sysroots

[Antonin Godard]

Hi,

On Thu Jul 30, 2026 at 1:39 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
>
> On 7/29/26 12:02 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> The sysroot in the standard and the extensible SDKs are managed
>> differently. Detail this in the Sysroots section.
>> 
>> [YOCTO #14830]
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/sdk-manual/intro.rst | 15 +++++++++++++++
>>   1 file changed, 15 insertions(+)
>> 
>> diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
>> index 8ccbcfa20..2e5f73f0b 100644
>> --- a/documentation/sdk-manual/intro.rst
>> +++ b/documentation/sdk-manual/intro.rst
>> @@ -123,6 +123,21 @@ sysroot is based on the target root filesystem image that is built by
>>   the OpenEmbedded build system and uses the same metadata configuration
>>   used to build the cross-toolchain.
>>   
>> +However, the extensible and standard SDKs sysroot differ in content:
>> +
>
> Why did we stop referring to the Sysroot term (:term:`Sysroot`)?

I can keep referring to it, but thought the first reference was enough. Will try
to refer to it when I can.

>> +-  The standard SDK sysroot only contains libraries and headers for the packages
>
> s/for/of/?
>
> I think we should also mention this brings the libraries and headers of 
> their dependencies (recursively) as well?

Correct, I'll add that

>> +   found in the :term:`TOOLCHAIN_TARGET_TASK` and :term:`TOOLCHAIN_HOST_TASK`
>> +   definitions, for the target and native sysroots respectively.
>> +
>
> I know we have a nativesdk OVERRIDE, so is it still a native/target 
> sysroot or should it be named nativesdk too (I've never built an SDK so 
> I don't know).

So here saying "native sysroot" makes sense if you're only look at the SDK.
Under yocto it's true that we have a distinction between native and nativesdk,
so maybe replacing "native" by "host" here would avoid the confusion in any
case. Will do

>> +   See :doc:`/sdk-manual/appendix-customizing-standard` to learn how to
>> +   customize it.
>> +
>> +-  The extensible SDK sysroot is completely managed by the ``devtool``
>
> Can we maybe point at some docs for devtool? From a quick grep, maybe 
> something in documentation/ref-manual/devtool-reference.rst?

Agreed, will add that

>> +   command-line tool, and its content is the same as the sysroot of the image
>> +   recipe for which the SDK was built.
>> +
>
> I guess we could show how to do this here?
>
> I think it should be something like:
>
> bitbake my-image -c populate_sdk
>
> (or maybe point at 
> https://docs.yoctoproject.org/sdk-manual/appendix-obtain.html#building-an-sdk-installer 
> ?).

Since there are already references to appendix-obtain and appendix-customizing I
think it's already enough?

>> +   See :doc:`/sdk-manual/appendix-customizing` to learn how to customize it.
>> +
>
> Thinking about it, we probably should update 
> documentation/ref-manual/terms.rst for the Sysroot entry in the glossary 
> to explain sysroot for the SDKs (or at the very least point at the 
> section here).

I'll see what could be done

Thanks!
Antonin

Re: [docs] [PATCH 4/5] sdk-manual: rename the section to remove "extensible"

[Antonin Godard]

Hi,

On Thu Jul 30, 2026 at 12:29 PM CEST, Quentin Schulz wrote:
> Hi Antonin,
>
> On 7/29/26 12:02 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> The SDK manual covers both the standard and extensible SDKs yet the
>> title does not imply that, so rename the section to "Yocto Project
>> Application Development and the Software Development Kit (SDK) Manual".
>> 
>
> Well, now it's the opposite :)

Not sure we understand this the same way, for me "SDK" could me either standard
or extensible.

>> As a consequence, rename the first section title and reword the intro.
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/index.rst            | 2 +-
>>   documentation/sdk-manual/index.rst | 6 +++---
>>   documentation/sdk-manual/intro.rst | 8 ++++----
>>   3 files changed, 8 insertions(+), 8 deletions(-)
>> 
>> diff --git a/documentation/index.rst b/documentation/index.rst
>> index afabb6615..d8603c2f5 100644
>> --- a/documentation/index.rst
>> +++ b/documentation/index.rst
>> @@ -67,7 +67,7 @@ infrastructure.
>>      Linux Kernel Development Manual <kernel-dev/index>
>>      Security Manual <security-manual/index>
>>      Profile and Tracing Manual <profile-manual/index>
>> -   Application Development and the Extensible SDK (eSDK) <sdk-manual/index>
>> +   Application Development and SDK Manual <sdk-manual/index>
>>      Toaster Manual <toaster-manual/index>
>>      Test Environment Manual <test-manual/index>
>>      BitBake User Manual <bitbake>
>> diff --git a/documentation/sdk-manual/index.rst b/documentation/sdk-manual/index.rst
>> index dc7186b91..477274ab9 100644
>> --- a/documentation/sdk-manual/index.rst
>> +++ b/documentation/sdk-manual/index.rst
>> @@ -1,8 +1,8 @@
>>   .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
>>   
>> -========================================================================================
>> -Yocto Project Application Development and the Extensible Software Development Kit (eSDK)
>> -========================================================================================
>> +===================================================================================
>> +Yocto Project Application Development and the Software Development Kit (SDK) Manual
>> +===================================================================================
>>   
>
> Maybe "Software Development Kits (SDK/eSDK)"?

I like this too, makes it extra clear, I'll go with:

"Application Development and Software Development Kits (SDK/eSDK) Manual"

>>   |
>>   
>> diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
>> index 53246bd9a..8ccbcfa20 100644
>> --- a/documentation/sdk-manual/intro.rst
>> +++ b/documentation/sdk-manual/intro.rst
>> @@ -4,11 +4,11 @@
>>   Introduction
>>   ************
>>   
>> -eSDK Introduction
>> -=================
>> +SDK Introduction
>
> SDK/eSDK?

Or just "Introduction" :)

>> +================
>>   
>> -Welcome to the Yocto Project Application Development and the Extensible
>> -Software Development Kit (eSDK) manual. This manual
>> +Welcome to the Yocto Project Application Development and the
>> +Software Development Kit (SDK) manual. This manual
>
> Ditto.
>
> It's a bit confusing to use SDK as 'either "standard" SDK or eSDK' and 
> also '"standard" SDK'. I don't have anything to suggest though :/

With the new title this should fix the issue.

Antonin