[v3,2/3] sdk-manual: extensible.rst: update devtool ide-sdk

From: Adrian Freihofer <adrian.freihofer@gmail.com>

Replace
  devtool ide-sdk --debug-build-config
by
  devtool modify --debug-build

This change was introduced with commit
https://git.yoctoproject.org/poky/commit/?id=1f7eb26c947dde14698ae6e2ab88f0637027f4cb

Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
---
 documentation/sdk-manual/extensible.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

Hi Adrian, Antonin,

On 1/14/25 12:31 AM, Adrian Freihofer via lists.yoctoproject.org wrote:
> From: Adrian Freihofer <adrian.freihofer@gmail.com>
> 
> Replace
>    devtool ide-sdk --debug-build-config
> by
>    devtool modify --debug-build
> 
> This change was introduced with commit
> https://git.yoctoproject.org/poky/commit/?id=1f7eb26c947dde14698ae6e2ab88f0637027f4cb
> 
> Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
> ---
>   documentation/sdk-manual/extensible.rst | 7 ++++---
>   1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst
> index 9a50d7fc54c..3733997fac4 100644
> --- a/documentation/sdk-manual/extensible.rst
> +++ b/documentation/sdk-manual/extensible.rst
> @@ -669,7 +669,8 @@ The extensible SDK supports two different development modes.
>         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``, the
> +   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::
>   
> @@ -786,8 +787,8 @@ The extensible SDK supports two different development modes.
>      .. code-block:: sh
>   
>         # Create the SDK
> -      devtool modify cmake-example
> -      devtool ide-sdk cmake-example core-image-minimal -c --debug-build-config --ide=none
> +      devtool modify cmake-example --debug-build
> +      devtool ide-sdk cmake-example core-image-minimal -c --ide=none
>   

Considering the commit log that introduced this change, I wonder if we 
should mention this in the known issues of older releases, though I 
guess the whole example simply doesn't work?

Also, we should probably highlight this change in the migration manual 
somehow?

What do you think?

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

Thanks!
Quentin

Hi Quentin

Am Di., 14. Jan. 2025 um 11:10 Uhr schrieb Quentin Schulz <
quentin.schulz@cherry.de>:

> Hi Adrian, Antonin,
>
> On 1/14/25 12:31 AM, Adrian Freihofer via lists.yoctoproject.org wrote:
> > From: Adrian Freihofer <adrian.freihofer@gmail.com>
> >
> > Replace
> >    devtool ide-sdk --debug-build-config
> > by
> >    devtool modify --debug-build
> >
> > This change was introduced with commit
> >
> https://git.yoctoproject.org/poky/commit/?id=1f7eb26c947dde14698ae6e2ab88f0637027f4cb
> >
> > Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
> > ---
> >   documentation/sdk-manual/extensible.rst | 7 ++++---
> >   1 file changed, 4 insertions(+), 3 deletions(-)
> >
> > diff --git a/documentation/sdk-manual/extensible.rst
> b/documentation/sdk-manual/extensible.rst
> > index 9a50d7fc54c..3733997fac4 100644
> > --- a/documentation/sdk-manual/extensible.rst
> > +++ b/documentation/sdk-manual/extensible.rst
> > @@ -669,7 +669,8 @@ The extensible SDK supports two different
> development modes.
> >         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``, the
> > +   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::
> >
> > @@ -786,8 +787,8 @@ The extensible SDK supports two different
> development modes.
> >      .. code-block:: sh
> >
> >         # Create the SDK
> > -      devtool modify cmake-example
> > -      devtool ide-sdk cmake-example core-image-minimal -c
> --debug-build-config --ide=none
> > +      devtool modify cmake-example --debug-build
> > +      devtool ide-sdk cmake-example core-image-minimal -c --ide=none
> >
>
> Considering the commit log that introduced this change, I wonder if we
> should mention this in the known issues of older releases, though I
> guess the whole example simply doesn't work?

Well, all examples have always worked. There is only one detail that did
not work
When devtool ide-sdk was called with the --debug-build option, a build
configuration
for the IDE should be generated that compiles with e.g. -Og instead of -O2.
From the
user's point of view, debugging did work, but with still optimized code. So
there is
definitely a better user experience now than before. But it has always
worked
reasonably well.
The VSCode bitbake plugin called devtool ide-sdk without --debug-build,
which was also
not ideal and has now also been improved. However, this also means that the
broken
function was not available for UI users with older releases.

>
> Also, we should probably highlight this change in the migration manual
> somehow?
>
Assuming that the feature has not been used that much so far, I would
announce it as a
new feature of devtool modify and mention that the same but buggy feature
has been
removed from devtool ide-sdk. I can send something like this going to the
devtool section:

   -  Replace the anyway broken ``--debug-build-config`` option from
      ``devtool ide-sdk`` by a new ``--debug-build`` option of
      ``devtool modify``. The new workflow is now::

         devtool modify my-recipe --debug-build
         devtool ide-sdk my-recipe my-image

Thank you!
Adrian


> What do you think?
>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
> in any case.
>
> Thanks!
> Quentin
>

Hi Adrian,

On 1/14/25 7:21 PM, Adrian Freihofer via lists.yoctoproject.org wrote:
> Hi Quentin
> 
> Am Di., 14. Jan. 2025 um 11:10 Uhr schrieb Quentin Schulz <
> quentin.schulz@cherry.de>:
> 
>> Hi Adrian, Antonin,
>>
>> On 1/14/25 12:31 AM, Adrian Freihofer via lists.yoctoproject.org wrote:
>>> From: Adrian Freihofer <adrian.freihofer@gmail.com>
>>>
>>> Replace
>>>     devtool ide-sdk --debug-build-config
>>> by
>>>     devtool modify --debug-build
>>>
>>> This change was introduced with commit
>>>
>> https://git.yoctoproject.org/poky/commit/?id=1f7eb26c947dde14698ae6e2ab88f0637027f4cb
>>>
>>> Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
>>> ---
>>>    documentation/sdk-manual/extensible.rst | 7 ++++---
>>>    1 file changed, 4 insertions(+), 3 deletions(-)
>>>
>>> diff --git a/documentation/sdk-manual/extensible.rst
>> b/documentation/sdk-manual/extensible.rst
>>> index 9a50d7fc54c..3733997fac4 100644
>>> --- a/documentation/sdk-manual/extensible.rst
>>> +++ b/documentation/sdk-manual/extensible.rst
>>> @@ -669,7 +669,8 @@ The extensible SDK supports two different
>> development modes.
>>>          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``, the
>>> +   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::
>>>
>>> @@ -786,8 +787,8 @@ The extensible SDK supports two different
>> development modes.
>>>       .. code-block:: sh
>>>
>>>          # Create the SDK
>>> -      devtool modify cmake-example
>>> -      devtool ide-sdk cmake-example core-image-minimal -c
>> --debug-build-config --ide=none
>>> +      devtool modify cmake-example --debug-build
>>> +      devtool ide-sdk cmake-example core-image-minimal -c --ide=none
>>>
>>
>> Considering the commit log that introduced this change, I wonder if we
>> should mention this in the known issues of older releases, though I
>> guess the whole example simply doesn't work?
> 
> Well, all examples have always worked. There is only one detail that did
> not work
> When devtool ide-sdk was called with the --debug-build option, a build
> configuration
> for the IDE should be generated that compiles with e.g. -Og instead of -O2.
>  From the
> user's point of view, debugging did work, but with still optimized code. So
> there is
> definitely a better user experience now than before. But it has always
> worked
> reasonably well.
> The VSCode bitbake plugin called devtool ide-sdk without --debug-build,
> which was also
> not ideal and has now also been improved. However, this also means that the
> broken
> function was not available for UI users with older releases.
> 

Ok, thanks for the explanation.

>>
>> Also, we should probably highlight this change in the migration manual
>> somehow?
>>
> Assuming that the feature has not been used that much so far, I would

Well, I don't think we have telemetry in there so who knows if it isn't 
already widely used :)

> announce it as a
> new feature of devtool modify and mention that the same but buggy feature
> has been
> removed from devtool ide-sdk. I can send something like this going to the
> devtool section:
> 
>     -  Replace the anyway broken ``--debug-build-config`` option from
>        ``devtool ide-sdk`` by a new ``--debug-build`` option of
>        ``devtool modify``. The new workflow is now::
> 
>           devtool modify my-recipe --debug-build
>           devtool ide-sdk my-recipe my-image
> 

I would put this into the migration manual for the upcoming release 
which explains that it changed. The issue is not documenting the change 
in the documentation part itself, that doesn't matter much, but rather 
that something is required on the user side to debug builds.

Considering that devtool ide-sdk will fail if --debug-build-config is 
passed, I guess it's not THAT big of a deal because it'll prompt users 
to check for a solution, but highlighting it in the migration manual 
could help a few users avoid having to look for the new way to do it (or 
debug their setup/ask for help on the ML).

Cheers,
Quentin