[PATCH v3 4/9] buildman: Convert documentation to rST

[Quentin Schulz]

Hi Simon,

On 11/6/22 00:04, Simon Glass wrote:
> Convert the buildman documentation to rST format and include it in the
> 'build' section.
> 
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
[...]
> +Selecting which boards to build
> +-------------------------------
> +
> +Buildman lets you build all boards, or a subset. Specify the subset by passing
> +command-line arguments that list the desired build target, architecture,
> +CPU, board name, vendor, SoC or options. Multiple arguments are allowed. Each
> +argument will be interpreted as a regular expression, so behaviour is a superset
> +of exact or substring matching. Examples are:
> +
> +'tegra20'

I would have made those list items, but it's a matter of taste I guess :)

[...]
> +The full build output in this case is available in::
> +
> +   ../lcd9b/12_of_18_gd92aff7_lcd--Add-support-for/lubbock/
> +
> +Files:
> +
> +done

Ditto.

[...]
> +This shows that commit 19 has reduced codesize for arm slightly and increased
> +it for powerpc. This increase was offset in by reductions in rodata and
> +data/bss.
> +
> +Shown below the summary lines are the sizes for each board. Below each board
> +are the sizes for each function. This information starts with:
> +
> +add

Ditto.

> +   number of functions added / removed
> +
> +grow
> +   number of functions which grew / shrunk
> +
> +bytes
> +   number of bytes of code added to / removed from all functions, plus the total
> +   byte change in brackets
> +
> +The change seems to be that hash_command() has increased by more than the
> +do_mem_crc() function has decreased. The function sizes typically add up to
> +roughly the text area size, but note that every read-only section except
> +rodata is included in 'text', so the function total does not exactly
> +correspond.
> +
> +It is common when refactoring code for the rodata to decrease as the text size
> +increases, and vice versa.
> +
> +
> +.. _buildman_settings:
> +
> +The .buildman settings file
> +---------------------------
> +
> +The .buildman file provides information about the available toolchains and
> +also allows build flags to be passed to 'make'. It consists of several
> +sections, with the section name in square brackets. Within each section are
> +a set of (tag, value) pairs.
> +
> +'[toolchain]' section

Ditto.

[...]
> +Other options
> +-------------
> +
> +Buildman has various other command-line options. Try --help to see them.
> +
> +To find out what toolchain prefix buildman will use for a build, use the -A
> +option.
> +
> +To request that compiler warnings be promoted to errors, use -E. This passes the
> +-Werror flag to the compiler. Note that the build can still produce warnings
> +with -E, e.g. the migration warnings::
> +
> +   --------------------- WARNING ----------------------
> +   This board does not use CONFIG_DM_MMC. Please update
> +   ...
> +   ----------------------------------------------------
> +

Those are still = and not -, I assume the result of a regexp a bit too 
aggressive :)

Otherwise looks fine,
Reviewed-by: Quentin Schulz <foss+uboot at 0leil.net>

Cheers,
Quentin