Makefile: rust-analyzer better error handling, documentation
v2 cover Makefile: rust-analyzer better error handling, documentation
Changes since v1:
1) Thanks to Alice Ryhl for testing and reviewing v1. I had to drop both of those tags for this v2, because even though it is small, it's different enough to invalidate both, unfortunately.
2) Adopted Miguel Ojeda's suggestion of letting rust_is_available.sh report its results directly, thus improving the output, while also simplifying the patch.
3) As requested by Miguel, split out some new comment documentation for the rust-analyzer target into its own patch.
John Hubbard (2):
Makefile: rust-analyzer target: better error handling
Makefile: improve comment documentation for the rust-analyzer target
Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
base-commit: e5b3efbe1ab1793bb49ae07d56d0973267e65112
Signature · 1 line
2.45.2
PATCH v2 1/2 Makefile: rust-analyzer target: better error handling
1) Provide a better error message for the "Rust not available" case. Without this patch, one gets various misleading messages, such as:
"No rule to make target 'rust-analyzer'"
Instead, run scripts/rust_is_available.sh directly, as a prerequisite, and let that script report the cause of any problems, as well as providing a link to the documentation. Thanks to Miguel Ojeda for the idea of just letting rust_is_available.sh report its results directly.
The new output in the failure case looks like this:
$ make rust-analyzer *** *** Rust compiler 'rustc' could not be found. *** *** *** Please see Documentation/rust/quick-start.rst for details *** on how to set up the Rust support. *** make[1]: *** [/kernel_work/linux-github/Makefile:1975: rust-analyzer] Error 1 make: *** [Makefile:240: __sub-make] Error 2
--- Makefile | 1 + 1 file changed, 1 insertion(+)
Makefile +1 -0
@@ -1970,6 +1970,7 @@ tags TAGS cscope gtags: FORCE # IDE support targets PHONY += rust-analyzer rust-analyzer: + $(Q)$(CONFIG_SHELL) $(srctree)/scripts/rust_is_available.sh $(Q)$(MAKE) $(build)=rust $@ # Script to generate missing namespace dependencies
Signature · 1 line
2.45.2
Re: [PATCH v2 1/2] Makefile: rust-analyzer target: better error handling
Quoted 44 lines · John Hubbard
1) Provide a better error message for the "Rust not available" case. Without this patch, one gets various misleading messages, such as:
"No rule to make target 'rust-analyzer'"
Instead, run
scripts/rust_is_available.shdirectly, as a prerequisite, and let that script report the cause of any problems, as well as providing a link to the documentation. Thanks to Miguel Ojeda for the idea of just lettingrust_is_available.shreport its results directly.The new output in the failure case looks like this:
$ make rust-analyzer *** *** Rust compiler 'rustc' could not be found. *** *** *** Please see Documentation/rust/quick-start.rst for details *** on how to set up the Rust support. *** make[1]: *** [/kernel_work/linux-github/Makefile:1975: rust-analyzer] Error 1 make: *** [Makefile:240: __sub-make] Error 2Cc Alice Ryhl <[email protected]>Acked-by Miguel Ojeda <[email protected]>Signed-off-by John Hubbard <[email protected]>--- Makefile | 1 + 1 file changed, 1 insertion(+)Makefile +1
-0@@ -1970,6 +1970,7 @@ tags TAGS cscope gtags: FORCE # IDE support targets PHONY += rust-analyzer rust-analyzer: + $(Q)$(CONFIG_SHELL) $(srctree)/scripts/rust_is_available.sh $(Q)$(MAKE) $(build)=rust $@ # Script to generate missing namespace dependenciesSignature · 1 line
2.45.2
Re: [PATCH v2 1/2] Makefile: rust-analyzer target: better error handling
In reply to John HubbardQuoted 24 lines · John Hubbard
1) Provide a better error message for the "Rust not available" case. Without this patch, one gets various misleading messages, such as:
"No rule to make target 'rust-analyzer'"
Instead, run
scripts/rust_is_available.shdirectly, as a prerequisite, and let that script report the cause of any problems, as well as providing a link to the documentation. Thanks to Miguel Ojeda for the idea of just lettingrust_is_available.shreport its results directly.The new output in the failure case looks like this:
$ make rust-analyzer *** *** Rust compiler 'rustc' could not be found. *** *** *** Please see Documentation/rust/quick-start.rst for details *** on how to set up the Rust support. *** make[1]: *** [/kernel_work/linux-github/Makefile:1975: rust-analyzer] Error 1 make: *** [Makefile:240: __sub-make] Error 2
Quoted 3 lines
Cc Alice Ryhl <[email protected]>Acked-by Miguel Ojeda <[email protected]>Signed-off-by John Hubbard <[email protected]>
PATCH v2 2/2 Makefile: improve comment documentation for the rust-analyzer target
In reply to John HubbardReplace the cryptic phrase ("IDE support targets") that initially appears to be about how to support old hard drives, with a few sentences that explain what "make rust-analyzer" provides.
--- Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
Makefile +3 -1
@@ -1967,7 +1967,9 @@ quiet_cmd_tags = GEN $@ tags TAGS cscope gtags: FORCE $(call cmd,tags) -# IDE support targets +# Generate rust-project.json, which does for Rust what clangd's +# compile_commands.json does for C/C++: provides a symbol browsing database for +# code editors and IDEs (Integrated Development Environments). PHONY += rust-analyzer rust-analyzer: $(Q)$(CONFIG_SHELL) $(srctree)/scripts/rust_is_available.sh
Signature · 1 line
2.45.2
Re: [PATCH v2 2/2] Makefile: improve comment documentation for the rust-analyzer target
Quoted 28 lines · John Hubbard
Replace the cryptic phrase ("IDE support targets") that initially appears to be about how to support old hard drives, with a few sentences that explain what "make rust-analyzer" provides.
Cc Alice Ryhl <[email protected]>Cc Miguel Ojeda <[email protected]>Signed-off-by John Hubbard <[email protected]>--- Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)Makefile +3
-1@@ -1967,7 +1967,9 @@ quiet_cmd_tags = GEN $@ tags TAGS cscope gtags: FORCE $(call cmd,tags) -# IDE support targets +# Generate rust-project.json, which does for Rust what clangd's +# compile_commands.json does for C/C++: provides a symbol browsing database for +# code editors and IDEs (Integrated Development Environments). PHONY += rust-analyzer rust-analyzer: $(Q)$(CONFIG_SHELL) $(srctree)/scripts/rust_is_available.shSignature · 1 line
2.45.2
Alice Ryhl
reviewerRe: [PATCH v2 2/2] Makefile: improve comment documentation for the rust-analyzer target
In reply to John HubbardQuoted 17 lines · John Hubbard
Replace the cryptic phrase ("IDE support targets") that initially appears to be about how to support old hard drives, with a few sentences that explain what "make rust-analyzer" provides.
Cc Alice Ryhl <[email protected]>Cc Miguel Ojeda <[email protected]>Signed-off-by John Hubbard <[email protected]>--- Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)Makefile +0
-0
Makefile quiet_cmd_tags = GEN $@ · line 1972
Quoted 7 lines
Makefile +3
-1@@ -1967,7 +1967,9 @@ quiet_cmd_tags = GEN $@ tags TAGS cscope gtags: FORCE $(call cmd,tags) -# IDE support targets +# Generate rust-project.json, which does for Rust what clangd's +# compile_commands.json does for C/C++: provides a symbol browsing database for +# code editors and IDEs (Integrated Development Environments).
Is "symbol browsing database" the right word here? It's not actually a list of symbols, but instructions for how to compile the code.
Alice
Miguel Ojeda
Acked-byRe: [PATCH v2 2/2] Makefile: improve comment documentation for the rust-analyzer target
Quoted 3 lines · Alice Ryhl
Is "symbol browsing database" the right word here? It's not actually a list of symbols, but instructions for how to compile the code.
Yeah, I think the sentence mixes a bit what the file is with what (some of) the users of the file do with it.
What about something like (getting inspiration from the official documentation):
# Generate rust-project.json (a file that describes the
structure of non-Cargo Rust projects) for rust-analyzer (an implementation of the Language Server Protocol).
I would avoid mentioning compile_commands.json, since they are slightly different the Rust one does not really contain the compile commands.
As for "IDE", I am happy either way (i.e. removing it or not). Another alternative that may clarify by giving context could be "Editor / IDE" (since one may use LSP with "simple editors" and not "full IDEs" anyway).
With that changed, if Masahiro wants to pick these two up:
Otherwise I am happy to take them too.
Cheers,
Miguel
Re: [PATCH v2 2/2] Makefile: improve comment documentation for the rust-analyzer target
Quoted 14 lines · Miguel Ojeda
Quoted 3 lines · Alice Ryhl
Is "symbol browsing database" the right word here? It's not actually a list of symbols, but instructions for how to compile the code.
Yeah, I think the sentence mixes a bit what the file is with what (some of) the users of the file do with it.
What about something like (getting inspiration from the official documentation):
# Generate
rust-project.json(a file that describes the
structure of non-Cargo Rust projects) forrust-analyzer(an implementation of the Language Server Protocol).
Quoted 9 lines
I would avoid mentioning
compile_commands.json, since they are slightly different the Rust one does not really contain the compile commands.As for "IDE", I am happy either way (i.e. removing it or not). Another alternative that may clarify by giving context could be "Editor / IDE" (since one may use LSP with "simple editors" and not "full IDEs" anyway).
OK, with those changes applied (minus the backticks, which don't want to be in this particular Makefile), we have:
Author: John Hubbard <[email protected]> Date: Thu Jun 20 13:54:53 2024 -0700
Makefile: improve comment documentation for the rust-analyzer target
Replace the cryptic phrase ("IDE support targets") that initially appears to be about how to support old hard drives, with a few sentences that explain what "make rust-analyzer" provides.
Makefile +3 -1
@@ -1967,7 +1967,9 @@ quiet_cmd_tags = GEN $@ tags TAGS cscope gtags: FORCE $(call cmd,tags) -# IDE support targets +# Generate rust-project.json (a file that describes the structure of non-Cargo +# Rust projects) for rust-analyzer (an implementation of the Language Server +# Protocol). PHONY += rust-analyzer rust-analyzer: $(Q)$(CONFIG_SHELL) $(srctree)/scripts/rust_is_available.sh
Quoted 8 lines
With that changed, if Masahiro wants to pick these two up:
Acked-by Miguel Ojeda <[email protected]>Otherwise I am happy to take them too.
Cheers,
Miguel
I can send out a v3, I'll wait to see if there is any additional feedback first, though.
thanks,
Signature · 2 lines
John Hubbard NVIDIA