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