| Message ID | 20230901200353.90290-7-jmcosta944@gmail.com |
|---|---|
| State | Superseded |
| Delegated to: | Tom Rini |
| Headers | show |
| Series | Port gen_compile_commands.py from Linux to U-Boot | expand |
On Fri, Sep 01, 2023 at 10:03:53PM +0200, Joao Marcos Costa wrote: > 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. > > Signed-off-by: Joao Marcos Costa <jmcosta944@gmail.com> > --- > doc/develop/gen_compile_commands.rst | 46 ++++++++++++++++++++++++++++ This isn't included in one of the index files, which will be the first error 'make htmldocs' throws, and I think I saw other syntax errors as well in the file. The docs themselves look fine, thanks.
Hello, Em sáb., 2 de set. de 2023 às 15:11, Tom Rini <trini@konsulko.com> escreveu: > > This isn't included in one of the index files, which will be the first > error 'make htmldocs' throws, and I think I saw other syntax errors as > well in the file. The docs themselves look fine, thanks. > > -- > Tom > I'm not sure what's the most pertinent category in 'develop/index.rst'. Would 'general' be a good idea? I thought about putting it in the same category as checkpatch, but this isn't refactoring per se. Thanks.
On Sat, Sep 02, 2023 at 03:38:13PM +0200, João Marcos Costa wrote: > Hello, > > Em sáb., 2 de set. de 2023 às 15:11, Tom Rini <trini@konsulko.com> escreveu: > > > > > This isn't included in one of the index files, which will be the first > > error 'make htmldocs' throws, and I think I saw other syntax errors as > > well in the file. The docs themselves look fine, thanks. > > > > -- > > Tom > > > > I'm not sure what's the most pertinent category in 'develop/index.rst'. > > Would 'general' be a good idea? I thought about putting it in the same > category as checkpatch, but this isn't refactoring per se. So, the main use case is to make integration with IDEs easier? Maybe put it under doc/build/ or referenced from doc/build/tools.rst with a small section like "Integration with IDEs" and a few words about how some IDEs such as ... use Clangd LSP for ... and see :doc:... for more information on how to generate these files.
diff --git a/doc/develop/gen_compile_commands.rst b/doc/develop/gen_compile_commands.rst new file mode 100644 index 0000000000..09466938fe --- /dev/null +++ b/doc/develop/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/*_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/scripts/gen_compile_commands.py b/scripts/gen_compile_commands.py index 1a9c49b34a..f0c6bafdc5 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/develop/gen_compile_commands.rst # """A tool for generating compile_commands.json in U-Boot."""
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. Signed-off-by: Joao Marcos Costa <jmcosta944@gmail.com> --- doc/develop/gen_compile_commands.rst | 46 ++++++++++++++++++++++++++++ scripts/gen_compile_commands.py | 1 + 2 files changed, 47 insertions(+) create mode 100644 doc/develop/gen_compile_commands.rst