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 <jmcosta...@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 <tmroe...@google.com>
# Ported and modified for U-Boot by Joao Marcos Costa <jmcosta...@gmail.com>
+# Briefly documented at doc/build/gen_compile_commands.rst
#
"""A tool for generating compile_commands.json in U-Boot."""
