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
+
+====================
+gen_compile_commands
+====================
+
+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
+on parsing .cmd files, one needs to have a target (e.g. configs/xxx_defconfig)
+built before running the script.
+
+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::
+
+ ./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."""
--
2.41.0
