[PATCH v3 6/7] doc: add documentation for gen_compile_commands.py

[Heinrich Schuchardt]

On 9/2/23 16:53, Joao Marcos Costa wrote:
> This documentation briefly explains what is a compilation database,
> and how to use the script to generate one.
>
> This is not a portage, as there was no original documentation in the
> Linux sources.
>
> Acknowledge the documentation in the script's header and in doc/build
> index.
>
> Signed-off-by: Joao Marcos Costa <jmcosta944 at gmail.com>
> ---
>   doc/build/gen_compile_commands.rst | 46 ++++++++++++++++++++++++++++++
>   doc/build/index.rst                |  1 +
>   scripts/gen_compile_commands.py    |  1 +
>   3 files changed, 48 insertions(+)
>   create mode 100644 doc/build/gen_compile_commands.rst
>
> diff --git a/doc/build/gen_compile_commands.rst b/doc/build/gen_compile_commands.rst
> new file mode 100644
> index 0000000000..6b32eb678a
> --- /dev/null
> +++ b/doc/build/gen_compile_commands.rst
> @@ -0,0 +1,46 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +====================

Thanks for documenting the script.

This line is not needed.

> +gen_compile_commands
Nobody who is unaware of the script would know what this heading relates
too. How about:

'Create build data base for IDEs'

> +====================
> +
> +gen_compile_commands (scripts/gen_compile_commands.py) is a script used to
> +generate a compilation database (compile_commands.json). This database consists
> +of an array of "command objects" describing how each translation unit was
> +compiled.
> +
> +Example::
> +
> +  {
> +  "command": "gcc -Wp,-MD,arch/x86/cpu/.lapic.o.d -nostdinc -isystem (...)"
> +  "directory": "/home/jmcosta/u-boot",
> +  "file": "/home/jmcosta/u-boot/arch/x86/cpu/lapic.c"
> +  }
> +
> +Such information comes from parsing the respective .cmd file of each translation
> +unit. In the previous example, that would be `arch/x86/cpu/.lapic.o.cmd`.
> +
> +The compilation database is quite useful for text editors (and IDEs) that use
> +Clangd LSP. It allows jumping to definitions and declarations. Since it relies

Given this information I would have no clue which IDE or editor you
might possibly refer to.

Please, indicate the IDEs and how they have to be set up to make use of
the generated file or where to find such information.

> +on parsing .cmd files, one needs to have a target (e.g. configs/xxx_defconfig)
> +built before running the script.

Does this imply references are inaccurate or missing once I have edited
files and not recompiled yet?

> +
> +Example::
> +
> +  make sandbox_defconfig
> +  make
> +  ./scripts/gen_compile_commands.py
> +
> +The database will be in the root of the repository. No further modifications are
> +needed for it to be usable by the LSP, unless you set a name for the database
> +other than it's default one (compile_commands.json).
> +
> +Options
> +=======
> +
> +For further details on how to use the script and its options, please refer to
> +its help message, as in the example below.
> +
> +Help::

There is not much information in the online help. The online help refers
to 'kernel build' which seems wrong.

Please, provide an accurate description here.

Best regards

Heinrich

> +
> +  ./scripts/gen_compile_commands.py --help
> diff --git a/doc/build/index.rst b/doc/build/index.rst
> index 64e66491bd..7a4507b574 100644
> --- a/doc/build/index.rst
> +++ b/doc/build/index.rst
> @@ -14,3 +14,4 @@ Build U-Boot
>      tools
>      buildman
>      documentation
> +   gen_compile_commands
> diff --git a/scripts/gen_compile_commands.py b/scripts/gen_compile_commands.py
> index 1a9c49b34a..aa52e88e18 100755
> --- a/scripts/gen_compile_commands.py
> +++ b/scripts/gen_compile_commands.py
> @@ -5,6 +5,7 @@
>   #
>   # Author: Tom Roeder <tmroeder at google.com>
>   # Ported and modified for U-Boot by Joao Marcos Costa <jmcosta944 at gmail.com>
> +# Briefly documented at doc/build/gen_compile_commands.rst
>   #
>   """A tool for generating compile_commands.json in U-Boot."""
>