[PATCH v2 0/2] Update the devtool quick reference document

[PATCH v2 0/2] Update the devtool quick reference document

[Antonin Godard]

* Refresh command outputs from `devtool --help` and `devtool add
  --help`.
* Add some brief details on the subcommands that were previously
  undocumented, and the more recent commands that weren't documented
  yet.
* The remaining subcommands are still present in devtool, so leave them
  as-is.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v2:
- configure-help: Give an example of what the command will output for.
- ide-sdk: mention that like deploy-target an ssh server must be running
  on the target.
- Link to v1: https://lore.kernel.org/r/20241017-devtool-improvements-v1-0-2bacc656fe39@bootlin.com

---
Antonin Godard (2):
      ref-manual: devtool-reference: refresh example outputs
      ref-manual: devtool-reference: document missing commands

 documentation/ref-manual/devtool-reference.rst | 72 ++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 11 deletions(-)
---
base-commit: e4b64514673471850635a8dbbf62f34e710e276a
change-id: 20241017-devtool-improvements-68a7c869e2b4

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>

[PATCH v2 1/2] ref-manual: devtool-reference: refresh example outputs

[Antonin Godard]

Previous outputs were missing some commands and options, some others
were obsolete.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/devtool-reference.rst | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 9319addc3c611ee183ad069bf7e41d14811b33ce..9c36195c5a5a2405cf8e3a562a2a53291e97c859 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -24,7 +24,7 @@ The ``devtool`` command line is organized similarly to Git in that it
 has a number of sub-commands for each function. You can run
 ``devtool --help`` to see all the commands::
 
-   $ devtool -h
+   $ devtool --help
    NOTE: Starting bitbake server...
    usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] [--color COLOR] [-h] <subcommand> ...
 
@@ -50,6 +50,7 @@ has a number of sub-commands for each function. You can run
        search                Search available recipes
      Working on a recipe in the workspace:
        build                 Build a recipe
+       ide-sdk               Setup the SDK and configure the IDE
        rename                Rename a recipe file in the workspace
        edit-recipe           Edit a recipe file
        find-recipe           Find a recipe file
@@ -63,17 +64,11 @@ has a number of sub-commands for each function. You can run
        build-image           Build image including workspace recipe packages
      Advanced:
        create-workspace      Set up workspace in an alternative location
+       import                Import exported tar archive into workspace
+       export                Export workspace into a tar archive
        extract               Extract the source for an existing recipe
        sync                  Synchronize the source tree for an existing recipe
        menuconfig            Alter build-time configuration for a recipe
-       import                Import exported tar archive into workspace
-       export                Export workspace into a tar archive
-     other:
-       selftest-reverse      Reverse value (for selftest)
-       pluginfile            Print the filename of this plugin
-       bbdir                 Print the BBPATH directory of this plugin
-       count                 How many times have this plugin been registered.
-       multiloaded           How many times have this plugin been initialized
    Use devtool <subcommand> --help to get help on a specific command
 
 As directed in the general help output, you can
@@ -82,8 +77,8 @@ using ``--help``::
 
    $ devtool add --help
    NOTE: Starting bitbake server...
-   usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] [--npm-dev] [--version VERSION] [--no-git] [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH] [--binary] [--also-native] [--src-subdir SUBDIR] [--mirrors]
-                      [--provides PROVIDES]
+   usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] [--npm-dev] [--no-pypi] [--version VERSION] [--no-git] [--srcrev SRCREV | --autorev]
+                      [--srcbranch SRCBRANCH] [--binary] [--also-native] [--src-subdir SUBDIR] [--mirrors] [--provides PROVIDES]
                       [recipename] [srctree] [fetchuri]
 
    Adds a new recipe to the workspace to build a specified source tree. Can optionally fetch a remote URI and unpack it to create the source tree.
@@ -99,6 +94,7 @@ using ``--help``::
      --no-same-dir         Force build in a separate build directory
      --fetch URI, -f URI   Fetch the specified URI and extract it to create the source tree (deprecated - pass as positional argument instead)
      --npm-dev             For npm, also fetch devDependencies
+     --no-pypi             Do not inherit pypi class
      --version VERSION, -V VERSION
                            Version to use within recipe (PV)
      --no-git, -g          If fetching source, do not set up source tree as a git repository

-- 
2.46.1

[PATCH v2 2/2] ref-manual: devtool-reference: document missing commands

[Antonin Godard]

Give a brief description for important commands that made it into
devtool or that were missing from this quick reference document.

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

diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 9c36195c5a5a2405cf8e3a562a2a53291e97c859..4862350f92781c80187a951f149ac2e5ef273510 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -463,6 +463,20 @@ Here is an example that resets the workspace directory that contains the
    NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
    $
 
+.. _devtool-finish-working-on-a-recipe:
+
+Finish Working on a Recipe
+==========================
+
+Use the ``devtool finish`` command to push any committed changes to the
+specified recipe in the specified layer and remove it from your workspace.
+
+This is roughly equivalent to the ``devtool update-recipe`` command followed by
+the ``devtool reset`` command. The changes must have been committed to the git
+repository created by ``devtool``. Here is an example::
+
+  $ devtool finish recipe /path/to/custom/layer
+
 .. _devtool-building-your-recipe:
 
 Building Your Recipe
@@ -614,3 +628,43 @@ a match.
 
 When you use the ``devtool search`` command, you must supply a keyword.
 The command uses the keyword when searching for a match.
+
+Alternatively, the ``devtool find-recipe`` command can be used to search for
+recipe files instead of recipe names. Likewise, you must supply a keyword.
+
+.. _devtool-get-the-configure-script-help:
+
+Get Information on Recipe Configuration Scripts
+===============================================
+
+Use the ``devtool configure-help`` command to get help on the configuration
+script options for a given recipe. You must supply the recipe name to the
+command. For example, it shows the output of ``./configure --help`` for
+``autotools``-based recipes.
+
+The ``configure-help`` command will also display the configuration options
+currently in use, including the ones passed through the :term:`EXTRA_OECONF`
+variable.
+
+.. _devtool-generate-an-ide-configuration-for-a-recipe:
+
+Generate an IDE Configuration for a Recipe
+==========================================
+
+The ``devtool ide-sdk`` automatically creates an IDE configuration and SDK to
+work on a given recipe. Depending on the ``--mode`` parameter, different types
+of SDKs are generated:
+
+-  ``modified`` mode: this creates an SDK and generates an IDE configuration in
+   the workspace directory.
+
+-  ``shared`` mode: this creates a cross-compiling toolchain and the
+   corresponding shared sysroot directories of the supplied recipe(s).
+
+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.
+
+For further details on the ``devtool ide-sdk`` command, see the
+":doc:`/sdk-manual/extensible`" chapter in the Yocto Project Application
+Development and the Extensible Software Development Kit (eSDK) manual.

-- 
2.46.1

Re: [PATCH v2 0/2] Update the devtool quick reference document

[Antonin Godard]

Hi Quentin,

On Tue Oct 22, 2024 at 10:37 AM CEST, Antonin Godard wrote:
> * Refresh command outputs from `devtool --help` and `devtool add
>   --help`.
> * Add some brief details on the subcommands that were previously
>   undocumented, and the more recent commands that weren't documented
>   yet.
> * The remaining subcommands are still present in devtool, so leave them
>   as-is.
>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
> Changes in v2:
> - configure-help: Give an example of what the command will output for.
> - ide-sdk: mention that like deploy-target an ssh server must be running
>   on the target.
> - Link to v1: https://lore.kernel.org/r/20241017-devtool-improvements-v1-0-2bacc656fe39@bootlin.com

What do you think of this v2?

I took note of your suggestions and added them here.

Thanks in advance,
Antonin

--
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [PATCH v2 2/2] ref-manual: devtool-reference: document missing commands

[Quentin Schulz]

Hi Antonin,

On 10/22/24 10:37 AM, Antonin Godard wrote:
> Give a brief description for important commands that made it into
> devtool or that were missing from this quick reference document.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/ref-manual/devtool-reference.rst | 54 ++++++++++++++++++++++++++
>   1 file changed, 54 insertions(+)
> 
> diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
> index 9c36195c5a5a2405cf8e3a562a2a53291e97c859..4862350f92781c80187a951f149ac2e5ef273510 100644
> --- a/documentation/ref-manual/devtool-reference.rst
> +++ b/documentation/ref-manual/devtool-reference.rst
> @@ -463,6 +463,20 @@ Here is an example that resets the workspace directory that contains the
>      NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
>      $
>   
> +.. _devtool-finish-working-on-a-recipe:
> +
> +Finish Working on a Recipe
> +==========================
> +
> +Use the ``devtool finish`` command to push any committed changes to the
> +specified recipe in the specified layer and remove it from your workspace.
> +
> +This is roughly equivalent to the ``devtool update-recipe`` command followed by
> +the ``devtool reset`` command. The changes must have been committed to the git
> +repository created by ``devtool``. Here is an example::
> +
> +  $ devtool finish recipe /path/to/custom/layer
> +
>   .. _devtool-building-your-recipe:
>   
>   Building Your Recipe
> @@ -614,3 +628,43 @@ a match.
>   
>   When you use the ``devtool search`` command, you must supply a keyword.
>   The command uses the keyword when searching for a match.
> +
> +Alternatively, the ``devtool find-recipe`` command can be used to search for
> +recipe files instead of recipe names. Likewise, you must supply a keyword.
> +
> +.. _devtool-get-the-configure-script-help:
> +
> +Get Information on Recipe Configuration Scripts
> +===============================================
> +
> +Use the ``devtool configure-help`` command to get help on the configuration
> +script options for a given recipe. You must supply the recipe name to the
> +command. For example, it shows the output of ``./configure --help`` for
> +``autotools``-based recipes.

suggestion: maybe use :ref:`classes-autotools` here?

Cheers,
Quentin

Re: [PATCH v2 0/2] Update the devtool quick reference document

[Quentin Schulz]

Hi Antonin,

On 10/28/24 2:54 PM, Antonin Godard wrote:
> Hi Quentin,
> 
> On Tue Oct 22, 2024 at 10:37 AM CEST, Antonin Godard wrote:
>> * Refresh command outputs from `devtool --help` and `devtool add
>>    --help`.
>> * Add some brief details on the subcommands that were previously
>>    undocumented, and the more recent commands that weren't documented
>>    yet.
>> * The remaining subcommands are still present in devtool, so leave them
>>    as-is.
>>
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>> Changes in v2:
>> - configure-help: Give an example of what the command will output for.
>> - ide-sdk: mention that like deploy-target an ssh server must be running
>>    on the target.
>> - Link to v1: https://lore.kernel.org/r/20241017-devtool-improvements-v1-0-2bacc656fe39@bootlin.com
> 
> What do you think of this v2?
> 

Looking good. I'm a bit wary of giving my Reviewed-by on things I've 
never used though.

This looks like valid Sphinx and English to me, so that's how far I can 
go for this review :)

Cheers,
Quentin

Re: [PATCH v2 0/2] Update the devtool quick reference document

[Antonin Godard]

Hi Quentin,

On Mon Oct 28, 2024 at 3:27 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 10/28/24 2:54 PM, Antonin Godard wrote:
>> Hi Quentin,
>>
>> On Tue Oct 22, 2024 at 10:37 AM CEST, Antonin Godard wrote:
>>> * Refresh command outputs from `devtool --help` and `devtool add
>>>    --help`.
>>> * Add some brief details on the subcommands that were previously
>>>    undocumented, and the more recent commands that weren't documented
>>>    yet.
>>> * The remaining subcommands are still present in devtool, so leave them
>>>    as-is.
>>>
>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>> ---
>>> Changes in v2:
>>> - configure-help: Give an example of what the command will output for.
>>> - ide-sdk: mention that like deploy-target an ssh server must be running
>>>    on the target.
>>> - Link to v1: https://lore.kernel.org/r/20241017-devtool-improvements-v1-0-2bacc656fe39@bootlin.com
>>
>> What do you think of this v2?
>>
>
> Looking good. I'm a bit wary of giving my Reviewed-by on things I've
> never used though.
>
> This looks like valid Sphinx and English to me, so that's how far I can
> go for this review :)
>
> Cheers,
> Quentin

Thanks for the review!
And I'll add the `ref-classes-autotools` suggestion from the other mail.

Cheers,
Antonin

--
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com