Re: [docs] [PATCH v2] doc/user-manual: Refresh help output

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Yoann,

On Fri Oct 18, 2024 at 11:36 PM CEST, Yoann Congal via lists.yoctoproject.org wrote:
> From: Yoann Congal <yoann.congal@smile.fr>
>
> In commit 9257c48c3e36 ("Group and reorder options in bitbake help"),
> help output was changed, update the doc to match the new output.
>
> Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
> ---
> v1->v2: Review from Quentin Schulz
>  * Add Reviewed-By
>  * Add a comment with the command that generated the output
>  * whitespace cleanup
> ---
>  .../bitbake-user-manual-intro.rst             | 174 ++++++++++--------
>  1 file changed, 100 insertions(+), 74 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> index 35ffb88b0..539bb62d8 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> @@ -349,40 +349,84 @@ Usage and syntax
>  Following is the usage and syntax for BitBake::
>
>     $ bitbake -h
> -   Usage: bitbake [options] [recipename/target recipe:do_task ...]
> -
> -       Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
> -       It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
> -       will provide the layer, BBFILES and other configuration information.
> +   usage: bitbake [-s] [-e] [-g] [-u UI] [--version] [-h] [-f] [-c CMD]
> +                  [-C INVALIDATE_STAMP] [--runall RUNALL] [--runonly RUNONLY]
> +                  [--no-setscene] [--skip-setscene] [--setscene-only] [-n] [-p]
> +                  [-k] [-P] [-S SIGNATURE_HANDLER] [--revisions-changed]
> +                  [-b BUILDFILE] [-D] [-l DEBUG_DOMAINS] [-v] [-q]
> +                  [-w WRITEEVENTLOG] [-B BIND] [-T SERVER_TIMEOUT]
> +                  [--remote-server REMOTE_SERVER] [-m] [--token XMLRPCTOKEN]
> +                  [--observe-only] [--status-only] [--server-only] [-r PREFILE]
> +                  [-R POSTFILE] [-I EXTRA_ASSUME_PROVIDED]
> +                  [recipename/target ...]
> +
> +   It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH
> +   which will provide the layer, BBFILES and other configuration information.
> +
> +   General options:
> +     recipename/target     Execute the specified task (default is 'build') for
> +                           these target recipes (.bb files).
> +     -s, --show-versions   Show current and preferred versions of all recipes.
> +     -e, --environment     Show the global or per-recipe environment complete
> +                           with information about where variables were
> +                           set/changed.
> +     -g, --graphviz        Save dependency tree information for the specified
> +                           targets in the dot syntax.
> +     -u UI, --ui UI        The user interface to use (knotty, ncurses, taskexp,
> +                           taskexp_ncurses or teamcity - default knotty).
> +     --version             Show programs version and exit.
> +     -h, --help            Show this help message and exit.
>
> -   Options:
> -     --version             show program's version number and exit
> -     -h, --help            show this help message and exit
> -     -b BUILDFILE, --buildfile=BUILDFILE
> -                           Execute tasks from a specific .bb recipe directly.
> -                           WARNING: Does not handle any dependencies from other
> -                           recipes.
> -     -k, --continue        Continue as much as possible after an error. While the
> -                           target that failed and anything depending on it cannot
> -                           be built, as much as possible will be built before
> -                           stopping.
> +   Task control options:
>       -f, --force           Force the specified targets/task to run (invalidating
>                             any existing stamp file).
> -     -c CMD, --cmd=CMD     Specify the task to execute. The exact options
> +     -c CMD, --cmd CMD     Specify the task to execute. The exact options
>                             available depend on the metadata. Some examples might
>                             be 'compile' or 'populate_sysroot' or 'listtasks' may
>                             give a list of the tasks available.
> -     -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
> +     -C INVALIDATE_STAMP, --clear-stamp INVALIDATE_STAMP
>                             Invalidate the stamp for the specified task such as
>                             'compile' and then run the default task for the
>                             specified target(s).
> -     -r PREFILE, --read=PREFILE
> -                           Read the specified file before bitbake.conf.
> -     -R POSTFILE, --postread=POSTFILE
> -                           Read the specified file after bitbake.conf.
> -     -v, --verbose         Enable tracing of shell tasks (with 'set -x'). Also
> -                           print bb.note(...) messages to stdout (in addition to
> -                           writing them to ${T}/log.do_&lt;task&gt;).
> +     --runall RUNALL       Run the specified task for any recipe in the taskgraph
> +                           of the specified target (even if it wouldn't otherwise
> +                           have run).
> +     --runonly RUNONLY     Run only the specified task within the taskgraph of
> +                           the specified targets (and any task dependencies those
> +                           tasks may have).
> +     --no-setscene         Do not run any setscene tasks. sstate will be ignored
> +                           and everything needed, built.
> +     --skip-setscene       Skip setscene tasks if they would be executed. Tasks
> +                           previously restored from sstate will be kept, unlike
> +                           --no-setscene.
> +     --setscene-only       Only run setscene tasks, don't run any real tasks.
> +
> +   Execution control options:
> +     -n, --dry-run         Don't execute, just go through the motions.
> +     -p, --parse-only      Quit after parsing the BB recipes.
> +     -k, --continue        Continue as much as possible after an error. While the
> +                           target that failed and anything depending on it cannot
> +                           be built, as much as possible will be built before
> +                           stopping.
> +     -P, --profile         Profile the command and save reports.
> +     -S SIGNATURE_HANDLER, --dump-signatures SIGNATURE_HANDLER
> +                           Dump out the signature construction information, with
> +                           no task execution. The SIGNATURE_HANDLER parameter is
> +                           passed to the handler. Two common values are none and
> +                           printdiff but the handler may define more/less. none
> +                           means only dump the signature, printdiff means
> +                           recursively compare the dumped signature with the most
> +                           recent one in a local build or sstate cache (can be
> +                           used to find out why tasks re-run when that is not
> +                           expected)
> +     --revisions-changed   Set the exit code depending on whether upstream
> +                           floating revisions have changed or not.
> +     -b BUILDFILE, --buildfile BUILDFILE
> +                           Execute tasks from a specific .bb recipe directly.
> +                           WARNING: Does not handle any dependencies from other
> +                           recipes.
> +
> +   Logging/output control options:
>       -D, --debug           Increase the debug level. You can specify this more
>                             than once. -D sets the debug level to 1, where only
>                             bb.debug(1, ...) messages are printed to stdout; -DD
> @@ -392,65 +436,47 @@ Following is the usage and syntax for BitBake::
>                             -D only affects output to stdout. All debug messages
>                             are written to ${T}/log.do_taskname, regardless of the
>                             debug level.
> +     -l DEBUG_DOMAINS, --log-domains DEBUG_DOMAINS
> +                           Show debug logging for the specified logging domains.
> +     -v, --verbose         Enable tracing of shell tasks (with 'set -x'). Also
> +                           print bb.note(...) messages to stdout (in addition to
> +                           writing them to ${T}/log.do_<task>).
>       -q, --quiet           Output less log message data to the terminal. You can
>                             specify this more than once.
> -     -n, --dry-run         Don't execute, just go through the motions.
> -     -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
> -                           Dump out the signature construction information, with
> -                           no task execution. The SIGNATURE_HANDLER parameter is
> -                           passed to the handler. Two common values are none and
> -                           printdiff but the handler may define more/less. none
> -                           means only dump the signature, printdiff means compare
> -                           the dumped signature with the cached one.
> -     -p, --parse-only      Quit after parsing the BB recipes.
> -     -s, --show-versions   Show current and preferred versions of all recipes.
> -     -e, --environment     Show the global or per-recipe environment complete
> -                           with information about where variables were
> -                           set/changed.
> -     -g, --graphviz        Save dependency tree information for the specified
> -                           targets in the dot syntax.
> -     -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
> -                           Assume these dependencies don't exist and are already
> -                           provided (equivalent to ASSUME_PROVIDED). Useful to
> -                           make dependency graphs more appealing
> -     -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
> -                           Show debug logging for the specified logging domains
> -     -P, --profile         Profile the command and save reports.
> -     -u UI, --ui=UI        The user interface to use (knotty, ncurses, taskexp or
> -                           teamcity - default knotty).
> -     --token=XMLRPCTOKEN   Specify the connection token to be used when
> -                           connecting to a remote server.
> -     --revisions-changed   Set the exit code depending on whether upstream
> -                           floating revisions have changed or not.
> -     --server-only         Run bitbake without a UI, only starting a server
> -                           (cooker) process.
> -     -B BIND, --bind=BIND  The name/address for the bitbake xmlrpc server to bind
> +     -w WRITEEVENTLOG, --write-log WRITEEVENTLOG
> +                           Writes the event log of the build to a bitbake event
> +                           json file. Use '' (empty string) to assign the name
> +                           automatically.
> +
> +   Server options:
> +     -B BIND, --bind BIND  The name/address for the bitbake xmlrpc server to bind
>                             to.
> -     -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
> +     -T SERVER_TIMEOUT, --idle-timeout SERVER_TIMEOUT
>                             Set timeout to unload bitbake server due to
>                             inactivity, set to -1 means no unload, default:
>                             Environment variable BB_SERVER_TIMEOUT.
> -     --no-setscene         Do not run any setscene tasks. sstate will be ignored
> -                           and everything needed, built.
> -     --skip-setscene       Skip setscene tasks if they would be executed. Tasks
> -                           previously restored from sstate will be kept, unlike
> -                           --no-setscene
> -     --setscene-only       Only run setscene tasks, don't run any real tasks.
> -     --remote-server=REMOTE_SERVER
> +     --remote-server REMOTE_SERVER
>                             Connect to the specified server.
>       -m, --kill-server     Terminate any running bitbake server.
> +     --token XMLRPCTOKEN   Specify the connection token to be used when
> +                           connecting to a remote server.
>       --observe-only        Connect to a server as an observing-only client.
>       --status-only         Check the status of the remote bitbake server.
> -     -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
> -                           Writes the event log of the build to a bitbake event
> -                           json file. Use '' (empty string) to assign the name
> -                           automatically.
> -     --runall=RUNALL       Run the specified task for any recipe in the taskgraph
> -                           of the specified target (even if it wouldn't otherwise
> -                           have run).
> -     --runonly=RUNONLY     Run only the specified task within the taskgraph of
> -                           the specified targets (and any task dependencies those
> -                           tasks may have).
> +     --server-only         Run bitbake without a UI, only starting a server
> +                           (cooker) process.
> +
> +   Configuration options:
> +     -r PREFILE, --read PREFILE
> +                           Read the specified file before bitbake.conf.
> +     -R POSTFILE, --postread POSTFILE
> +                           Read the specified file after bitbake.conf.
> +     -I EXTRA_ASSUME_PROVIDED, --ignore-deps EXTRA_ASSUME_PROVIDED
> +                           Assume these dependencies don't exist and are already
> +                           provided (equivalent to ASSUME_PROVIDED). Useful to
> +                           make dependency graphs more appealing.
> +
> +..
> +    Bitbake help output generated with "stty columns 80; bin/bitbake -h"
>
>  .. _bitbake-examples:
>

Thank you, adding my +1 too.

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>

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