| Message ID | 20230902145310.107054-7-jmcosta944@gmail.com |
|---|---|
| State | Changes Requested |
| Delegated to: | Heinrich Schuchardt |
| Headers | show |
| Series | Port gen_compile_commands.py from Linux to U-Boot | expand |
On 9/2/23 16:53, 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 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 > + > +==================== Thanks for documenting the script. This line is not needed. > +gen_compile_commands Nobody who is unaware of the script would know what this heading relates too. How about: 'Create build data base 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`. > + > +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 Given this information I would have no clue which IDE or editor you might possibly refer to. Please, indicate the IDEs and how they have to be set up to make use of the generated file or where to find such information. > +on parsing .cmd files, one needs to have a target (e.g. configs/xxx_defconfig) > +built before running the script. Does this imply references are inaccurate or missing once I have edited files and not recompiled yet? > + > +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:: There is not much information in the online help. The online help refers to 'kernel build' which seems wrong. Please, provide an accurate description here. Best regards Heinrich > + > + ./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.""" >
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."""
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