On a fresh checkout, generating rust-project.json alone is not enough
for rust-analyzer to work reliably. The issue only becomes apparent
later when the LSP fails on a proc macro or binding types/functions.

Recommend running prepare together with the rust-analyzer target so the
generated files expected by rust-analyzer are available from the start.

Link: https://rust-for-linux.zulipchat.com/#narrow/channel/597064-rust-analyzer
Signed-off-by: Onur Özkan <work@onurozkan.dev>
---
 Documentation/rust/quick-start.rst                    | 2 +-
 Documentation/translations/zh_CN/rust/quick-start.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst
index a6ec3fa94d33..df5b54b51deb 100644
--- a/Documentation/rust/quick-start.rst
+++ b/Documentation/rust/quick-start.rst
@@ -314,7 +314,7 @@ definition, and other features.
 ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
 can be generated by the ``rust-analyzer`` Make target::
 
-	make LLVM=1 rust-analyzer
+	make LLVM=1 prepare rust-analyzer
 
 
 Configuration
diff --git a/Documentation/translations/zh_CN/rust/quick-start.rst b/Documentation/translations/zh_CN/rust/quick-start.rst
index 5f0ece6411f5..3f7efd3a63ad 100644
--- a/Documentation/translations/zh_CN/rust/quick-start.rst
+++ b/Documentation/translations/zh_CN/rust/quick-start.rst
@@ -291,7 +291,7 @@ rust-analyzer
 ``rust-analyzer`` 需要一个配置文件， ``rust-project.json``, 它可以由 ``rust-analyzer``
 Make 目标生成::
 
-       make LLVM=1 rust-analyzer
+       make LLVM=1 prepare rust-analyzer
 
 
 配置
-- 
2.51.2

On Wed May 13, 2026 at 10:19 AM BST, Onur Özkan wrote:
> On a fresh checkout, generating rust-project.json alone is not enough
> for rust-analyzer to work reliably. The issue only becomes apparent
> later when the LSP fails on a proc macro or binding types/functions.
>
> Recommend running prepare together with the rust-analyzer target so the
> generated files expected by rust-analyzer are available from the start.

This should be fixed by marking `prepare` as a dependency of `rust-analyzer`
instead.

Best,
Gary

>
> Link: https://rust-for-linux.zulipchat.com/#narrow/channel/597064-rust-analyzer
> Signed-off-by: Onur Özkan <work@onurozkan.dev>
> ---
>  Documentation/rust/quick-start.rst                    | 2 +-
>  Documentation/translations/zh_CN/rust/quick-start.rst | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst
> index a6ec3fa94d33..df5b54b51deb 100644
> --- a/Documentation/rust/quick-start.rst
> +++ b/Documentation/rust/quick-start.rst
> @@ -314,7 +314,7 @@ definition, and other features.
>  ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
>  can be generated by the ``rust-analyzer`` Make target::
>  
> -	make LLVM=1 rust-analyzer
> +	make LLVM=1 prepare rust-analyzer
>  
>  
>  Configuration
> diff --git a/Documentation/translations/zh_CN/rust/quick-start.rst b/Documentation/translations/zh_CN/rust/quick-start.rst
> index 5f0ece6411f5..3f7efd3a63ad 100644
> --- a/Documentation/translations/zh_CN/rust/quick-start.rst
> +++ b/Documentation/translations/zh_CN/rust/quick-start.rst
> @@ -291,7 +291,7 @@ rust-analyzer
>  ``rust-analyzer`` 需要一个配置文件， ``rust-project.json``, 它可以由 ``rust-analyzer``
>  Make 目标生成::
>  
> -       make LLVM=1 rust-analyzer
> +       make LLVM=1 prepare rust-analyzer
>  
>  
>  配置

On Wed, May 13, 2026 at 1:04 PM Gary Guo <gary@garyguo.net> wrote:
>
> This should be fixed by marking `prepare` as a dependency of `rust-analyzer`
> instead.

Onur suggested that in Zulip, but it is not a real dependency (in the
sense of generating the file) nor a hard one (in the sense that
rust-analyzer works to some degree without a build).

I am not opposed to it to make the target about "setup rust-analyzer"
rather than "just generate the file", since I think that is what most
people want, but I wonder if someone out there may be already relying
on generating the file without building.

Another alternative is an informational message about it as a middle
ground between "just in the docs" and "not being possible to avoid
part of the build" (and without introducing yet one more target, which
is another option too).

Cheers,
Miguel

On Wed May 13, 2026 at 12:20 PM BST, Miguel Ojeda wrote:
> On Wed, May 13, 2026 at 1:04 PM Gary Guo <gary@garyguo.net> wrote:
>>
>> This should be fixed by marking `prepare` as a dependency of `rust-analyzer`
>> instead.
>
> Onur suggested that in Zulip, but it is not a real dependency (in the
> sense of generating the file) nor a hard one (in the sense that
> rust-analyzer works to some degree without a build).
>
> I am not opposed to it to make the target about "setup rust-analyzer"
> rather than "just generate the file", since I think that is what most
> people want, but I wonder if someone out there may be already relying
> on generating the file without building.


Well, to me I have always run it in a build directory, as it expects a .config
file so I cannot run it just source tree only. Running it would also sync the
config, which would invoke rustc and others already due to rustc-option, so
arguably it's already running part of the build.

The only issue with "prepare" dependency is that it also builds the kernel
crate. But I suppose with the new build system update this won't be necessary?

Best,
Gary

>
> Another alternative is an informational message about it as a middle
> ground between "just in the docs" and "not being possible to avoid
> part of the build" (and without introducing yet one more target, which
> is another option too).
>
> Cheers,
> Miguel

On Wed, May 13, 2026 at 11:20 AM Onur Özkan <work@onurozkan.dev> wrote:
>
> diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst
> index a6ec3fa94d33..df5b54b51deb 100644
> --- a/Documentation/rust/quick-start.rst
> +++ b/Documentation/rust/quick-start.rst
> @@ -314,7 +314,7 @@ definition, and other features.
>  ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
>  can be generated by the ``rust-analyzer`` Make target::
>
> -       make LLVM=1 rust-analyzer
> +       make LLVM=1 prepare rust-analyzer

Perhaps we should add a brief sentence after this code block
explaining why the `prepare` is there, e.g. adapted from the commit
message:

    For the best experience, it is recommended to make ``prepare``
    together with the ``rust-analyzer`` target so that all generated
    files (e.g. proc macros) are available.

Cc'ing Tamir and Jesung.

Cheers,
Miguel