u-boot/doc/build/gen_compile_commands.rst
Joao Marcos Costa 3a83960b76 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>
2023-10-11 13:24:55 -04:00

83 lines
3.2 KiB
ReStructuredText

.. 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