doc: add documentation for gen_compile_commands.py

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>
Tested-by: Joao Paulo Goncalves <joao.goncalves@toradex.com>

2 files changed, 84 insertions, 0 deletions

diff --git a/doc/build/gen_compile_commands.rst b/doc/build/gen_compile_commands.rst
new file mode 100644
index 0000000..50305ce
--- /dev/null
+++ b/doc/build/gen_compile_commands.rst
@@ -0,0 +1,83 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+Create build database 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`.
+
+For more details on the database format, please refer to the official
+documentation at https://clang.llvm.org/docs/JSONCompilationDatabase.html.
+
+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
+
+Beware that depending on the changes you made to the project's source code, you
+may need to run the script again (presuming you recompiled your target, of
+course) to have an up-to-date database.
+
+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).
+
+Compatible IDEs
+===============
+
+Several popular integrated development environments (IDEs) support the use
+of JSON compilation databases for C/C++ development, making it easier to
+manage build configurations and code analysis. Some of these IDEs include:
+
+1. **Visual Studio Code (VS Code)**: IntelliSense in VS Code can be set up to
+   use compile_commands.json by following the instructions in
+   https://code.visualstudio.com/docs/cpp/faq-cpp#_how-do-i-get-intellisense-to-work-correctly.
+
+2. **CLion**: JetBrains' CLion IDE supports JSON compilation databases out
+   of the box. You can configure your project to use a compile_commands.json
+   file via the project settings. Details on setting up CLion with JSON
+   compilation databases can be found at
+   https://www.jetbrains.com/help/clion/compilation-database.html.
+
+3. **Qt Creator**: Qt Creator, a popular IDE for Qt development, also
+   supports compile_commands.json for C/C++ projects. Instructions on how to
+   use this feature can be found at
+   https://doc.qt.io/qtcreator/creator-clang-codemodel.html#using-compilation-databases.
+
+4. **Eclipse CDT**: Eclipse's C/C++ Development Tools (CDT) can be
+   configured to use JSON compilation databases for better project management.
+   You can find guidance on setting up JSON compilation database support at the
+   wiki: https://wiki.eclipse.org/CDT/User/NewIn910#Build.
+
+For Vim, Neovim, and Emacs, if you are using Clangd as your LSP, placing the
+compile_commands.json in the root of the repository should suffice to enable
+code navigation.
+
+Usage
+=====
+
+For further details on the script's 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 64e6649..7a4507b 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -14,3 +14,4 @@ Build U-Boot
    tools
    buildman
    documentation
+   gen_compile_commands