Skip to contentSkip to conversation

Makefile: rust-analyzer better error handling, documentation

PATCH Superseded John Hubbard 4 participants 9 messages Jun 20, 2024 – Jun 27, 2024

Subsystems (2)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 14427547dc1e..07308277a6f5 100644
@@ -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
Reviewed-by on v2 1/2
#2 lore raw

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.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
index 14427547dc1e..07308277a6f5 100644
@@ -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
reviewer Reviewed-by Tested-by on v2 1/2
#3 lore raw

Re: [PATCH v2 1/2] Makefile: rust-analyzer target: better error handling

In reply to John Hubbard
Quoted 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.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
Quoted 3 lines
#4 lore raw

PATCH v2 2/2 Makefile: improve comment documentation for the rust-analyzer target

In reply to 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]>
---
 Makefile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Makefile +3 -1
index 07308277a6f5..d22491184af6 100644
@@ -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
Reviewed-by on v2 2/2
#5 lore raw

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]>
---
 Makefile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Makefile +3 -1
index 07308277a6f5..d22491184af6 100644
@@ -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
reviewer
#6 lore raw

Re: [PATCH v2 2/2] Makefile: improve comment documentation for the rust-analyzer target

In reply to John Hubbard
Quoted 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]>
---
 Makefile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Makefile +0 -0
index 07308277a6f5..d22491184af6 100644

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

Acked-by
#7 lore raw

Re: [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

author Reviewed-by Finn Behrens Acked-by Miguel Ojeda
#8 lore raw

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) for rust-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
index 204e9be0e010..7db597bdb09d 100644
@@ -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:

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