diff options
author | Joao Marcos Costa <jmcosta944@gmail.com> | 2023-10-01 12:00:34 +0200 |
---|---|---|
committer | Tom Rini <trini@konsulko.com> | 2023-10-11 13:24:55 -0400 |
commit | 3a83960b76700db4aed576620a7cc15eea861c0e (patch) | |
tree | d130da4b1ade084bb3ba0347528575748acd9a7a /doc/build | |
parent | b703bda0bee82288793b9b8e7376b7826c58ce80 (diff) | |
download | u-boot-3a83960b76700db4aed576620a7cc15eea861c0e.zip u-boot-3a83960b76700db4aed576620a7cc15eea861c0e.tar.gz u-boot-3a83960b76700db4aed576620a7cc15eea861c0e.tar.bz2 |
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>
Diffstat (limited to 'doc/build')
-rw-r--r-- | doc/build/gen_compile_commands.rst | 83 | ||||
-rw-r--r-- | doc/build/index.rst | 1 |
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 |