rust-analyzer.toml

[Veykril]

This is a tracking issue/discussion for a potential rust-analyzer.toml. There have been a lot of requests for a per-project configuration in various issues, some clients like VSCode allow specifying settings per workspace, but usually these kinds of settings are not committed in a repo and are therefor usually not meant to necessarily configure r-a for the project specifically (like certain coding style settings, think of import merging etc.). Other related things might be requiring a special built procedure for a cargo project, prime example being https://github.com/rust-lang/rust which currently has a few suggested config lines in the dev guide which a user has to specify manually when they check out the repo locally, see https://rustc-dev-guide.rust-lang.org/building/suggested.html#configuring-rust-analyzer-for-rustc.

The idea is for the server to consume this file, so that you do not need a "rust-analyzer capable" LSP client to make use of it.

So there is clearly a need for a project config option like this, but here are few open questions.

• We could make use of the Cargo.toml metadata section instead, but that would only solve the problem for cargo based projects and it feels wrong to have certain settings in there opposed to a rust-analyzer.toml I believe.
  • I believe a rust-analyzer.toml to be the correct solution here.
• How does the priority work in regards to other mechanisms that set configurations? Ideally we'd favor a client's settings over rust-analyzer.toml, but we cannot know if a client sends us the default config for something or if its explicitly set, so we might have to bite the bullet and prefer rust-analyzer.toml.
• How would r-a look for these, is nesting allowed, that is can we have hierarchies for these files? We should probably stick to what other tools like rustfmt do in this regard. Hierarchies could pose an implementation problem though, as r-a only has global configurations (global in the sense of project wide, not per workspace). I am unsure how complex it would be to change that, so this might entail a bigger architecture change.
• What configs should be exposed in this
• We might want to allow to specifying search paths and their order for .rust-analyzer.toml files, allowing for both absolute and relative paths.

[Qix-]

Note: Highly suggest making this a dotfile (.rust-analyzer.toml). This would be aligned with other project-specific modifier configs such as .rustfmt.toml and .rusty-hook.toml, etc.

---

My usecase here is that I have a compiler_error!() macro in my project used for prevent builds if a target config isn't set up correctly (this is an edge-case, embedded project - not a typical library) that is #[cfg()]-gated. r-a chokes on it because it doesn't ever run with the correct target settings, making the some IDEs get really, really upset about things.

Having a per-project config file for r-a would allow me to specify a feature for analysis such as rust-analyzer or something like that that can be included in the #[cfg()] in order to avoid triggering such checks during analysis (but not in builds).

[emilio]

Yes please. We need something like this to provide proper integration with our build system and right now we can only provide that for vscode which is unfortunate.

How does the priority work in regards to other mechanisms that set configurations? Ideally we'd favor a client's settings over rust-analyzer.toml, but we cannot know if a client sends us the default config for something or if its explicitly set, so we might have to bite the bullet and prefer rust-analyzer.toml.

FWIW clangd has this feature (.clangd files) so may be worth checking out.

[Qix-]

How does the priority work in regards to other mechanisms that set configurations?

Doesn't this depend on how the client sends configs at all? Does r-a get its configuration via the client, or from the filesystem? If the former, then it's up to the client implementations to specify this. Ideally each would allow the user to specify the priorities of the searched configs, be able to merge them based on this, and then send the flattened config to r-a. I don't see how that's r-a's problem, really.

How would r-a look for these, is nesting allowed, that is can we have hierarchies for these files?

I don't think nesting is necessary. Keeping it clean and simple is probably the best route. It would also make debugging easier. (Again, this assumes that r-a is getting the config from the client directly, not from scouring the source tree etc.)

What configs should be exposed in this

If the above are true, then is this really a fix for r-a directly? It'd be up to the individual client implementations to handle these sort of semantics. Perhaps r-a could specify that .rust-analyzer.toml is a valid configuration spot and specify its syntax. Otherwise, the client libs should probably have the "sane" default of...

1. Any in-client overrides (directly specified in the config of the client)
2. Any user-local files (e.g. ~/.rust-analyzer.toml), if it exists
3. $(pwd)/.rust-analyzer.toml, if it exists
4. Some default set of configuration pertinent to getting r-a working in the respective client

As far as I understand, 1. and 4. are already the case. It's 2. and 3. that would have to be added.

Bonus points for allowing the user to specify search paths / their order for .rust-analyzer.toml files, allowing for both absolute and relative paths.

---

For anyone who wants a hack-and-slash workaround for Neovim that is non-standard, use this to initialize your init.vim:

function get_project_rustanalyzer_settings()
  local handle = io.open(vim.fn.resolve(vim.fn.getcwd() .. '/./.rust-analyzer.json'))
  if not handle then
    return {}
  end
  local out = handle:read("*a")
  handle:close()
  local config = vim.json.decode(out)
  if type(config) == "table" then
    return config
  end
  return {}
end

local lspflags = {
  rust_analyzer = {
    settings = {
      ['rust-analyzer'] = vim.tbl_deep_extend(
        "force",
        {
          -- Defaults (can be overridden by .rust-analyzer.json
        },
        get_project_rustanalyzer_settings(),
        {
          -- Overrides (forces these regardless of what's in .rust-analyzer.json
          procMacro = { enable = true },
          diagnostics = { disabled = {"inactive-code"} },
        }
      )
    }
  }
}

Then add a .rust-analyzer.json to your project (and either .gitignore it or add it to .git/info/exclude since it's non-standard):

{
        "cargo": {
                "features": [ "stm32f479" ]
        }
}

The downside is that this doesn't scan the directory hierarchy, so you have to open nvim from the directory that has the .rust-analyzer.json. I'll leave a hierarchy traversal modification to the code as an exercise to the reader 🙃 for now this works for me. A standardized way of doing this is still highly sought after, though.

[Veykril]

My initial thought here was for the server to consume the rust-analyzer.toml, not the client. Having the client consume it seems pointless, as that requires any LSP client to add special support for the rust-analyzer.toml format and ideally, rust-analyzer should have a baseline usability with any LSP compliant client.

---

Doesn't this depend on how the client sends configs at all? Does r-a get its configuration via the client, or from the filesystem? If the former, then it's up to the client implementations to specify this. Ideally each would allow the user to specify the priorities of the searched configs, be able to merge them based on this, and then send the flattened config to r-a. I don't see how that's r-a's problem, really.

So effectively with this rust-analyzer.toml added, we would have two ways of receiving config data, by the client and then per-project (per cargo workspace, opened project folder or crate even etc). I think we should always prefer the rust-analyzer.toml settings in that regard, the main reason I raised this question was because VSCode for example has global settings and local project settings but we can only treat them as "the client settings" in one unit, but that should be fine I think. Also note that not all config settings exposed by r-a today would make sense in the rust-analyzer.toml, an example being cargo.autoreload.

Bonus points for allowing the user to specify search paths / their order for .rust-analyzer.toml files, allowing for both absolute and relative paths.

That's a good point to consider.

---

The other points you've raised are somewhat moot with the thought of the server consuming it (I shouldve been clearer on that in the issue description, will edit) I think.

[Veykril]

Note: Highly suggest making this a dotfile (.rust-analyzer.toml). This would be aligned with other project-specific modifier configs such as .rustfmt.toml and .rusty-hook.toml, etc.

Allowing both rust-analyzer.toml and .rust-analyzer.toml seems fine to me (and given rustfmt consumes either forms as well it would only make sense for us to do the same)

[swarnimarun]

I remember another request for allowing Rust Analyzer to work without Cargo.toml aka over a
single file, I believe some config options were still required could we add them to rust-analyzer.toml would make scripting very easy if we could also have a rust-analyzer.toml globally. For say default custom global configuration?

And ensure that we use Cargo.toml or folder-local config only if they are present?

[Veykril]

Yes that somewhat plays into the third checkbox point, how r-a will look for the file and if nesting is allowed.

[alibektas]

@rustbot claim

So I am claiming this issue just to let everyone know that someone is working on it, although this won't be my number one priority for the first couple of weeks. If someone makes any progress within this time frame, please share it.

[alibektas]

Here is more or less a roadmap that I plan to follow : (The two names that I use here global and local are not very descriptive and probably will be changed to something more meaningful so do not mind them for now. And let .rust-analyzer.toml be RATOML for the time being. )

• Find out which configs are globally or locally-scoped. Create a PR where we possibly publish a document in which we briefly mention why a certain key-value pair is global or local.
• Replace rust_analyzer::config::ConfigData with GlobalConfigData LocalConfigData. As a result of this change rust_analyzer::config::Config's data will be of type GlobalConfigData. project_model::ProjectManifest is a good place to handle the discovery of the .rust-analyzer.toml file and finding out which configurations apply to a single ProjectManifest. This change will probably entail adding two more variants to ProjectManifest like ProjectManifest::ProjectJsonWithConf and ProjectManifest::CargoTomlWithConf. As I said before names are at this point arbitrary.
• Client settings and RATOML : During first handshakes between the server and the client config data are sent from the client to the server, which is how we have received configuration data so far. I plan to keep this as is and let server do a fresh start if any RATOML files are discovered. But this shouldn't tell you that the configs sent from the client have a higher priority than RATOML. Although I agree with @Veykril on the point that our hand is forced to choose either RATOML or client settings over another, the user should still be able to say that they want to use their own configs, which means that we need to add a KV pair that does just that : telling us which source we should prefer.
• First version of the RATOML : Although I may have sounded like this is something I want to have ready in the first version, I think we should first enable the use of a single RATOML file and gradually introduce nesting. So this version will use two sources to read configs from : (1) lsp_types::InitializeParams as sent by the client (2) RATOML.

[Qix-]

What does global and local solve? Why not just use a list of configs that overwrite each other in order, as I mentioned before?

[alibektas]

There are some configurations for which overwriting doesn't make much sense and can even be misleading. An example would be rust-analyzer.cachePriming.enable which states whether to Warm up caches on project load. ( this example may also be the wrong example I am not super sure about it but the point I am trying to make is that some configs are different from other in that they should be configured once). As to what goes in the RATOML there is no difference between globals and locals, they are configured exactly the same way it is just that for a global you can still nest it but only its first occurrence counts.

[Qix-]

I still don't see why global vs local makes more sense than multiple configs. Who cares if a second config overwrites the first in some weird way? That's on the user at that point.

[Veykril]

(That distinction came from a discussion Ali and I had elsewhere)

It is more that there a configs that apply to the server session as a whole and then there are configs that apply to individually loaded projects. There are also configs that do not make sense to be in the rust-analyzer.toml at all, like all the hover configs for example. Those are project irrelevant so they won't be configurable by the r-a toml file.

Though having a second look at things, I don't think there are configs that can't be applied on a per loaded project level (opposed to server session wide), aside from current implementation reasons maybe (files.watcher would be a server wide one, but at the same time that one should not be configured by the rust-analyzer.toml). So ye, the first step here is to classify all the current configs into the three buckets not applicable for rust-analyzer.toml, project/cargo workspace applicable and "global"/session wide. Then we can see whether that split makes sense or not.

[kornelski]

A rust-analyzer config file, or at least something in Cargo.toml would be great. I often need to enable most but not all non-default features of projects I'm working on to get useful autocomplete.

BTW: the rust-analyzer project is incredibly biased towards VSCode-only solutions. As someone who deliberately doesn't use this editor, I'm constantly frustrated by features that are missing from rust-analyzer, because they're solved by some VSCode-only doodad, and are unsupported or undocumented for other editors. Per-project config is one of these.

[alibektas]

@kornelski 👋 you can already use per-project configuration ( see #17058 ), there are two known issues to this which will be soon resolved ( see #17483 ). Please let me know if you have any suggestions/comments in general.

[Veykril]

BTW: the rust-analyzer project is incredibly biased towards VSCode-only solutions.

It is and we can't do anything about it. We are limited by what the LSP allows us to do. VSCode is the reference implementation that we maintain, we can't possible maintain editor extensions for all editors out there for obvious reasons.

[kornelski]

@alibektas that's a great news. However, I can't figure out what syntax it wants. I've tried rust-analyzer.toml in the project root with:

[rust-analyzer.cargo]
features = "all"
# or
[cargo]
features = "all"

but I don't see any effect, even after restarting RA manually.

@Veykril The problem is that if you don't make RA less VSCode-centric, nobody else will do that for you. The other editors say "this is just one of many LSP clients, we can't possibly test and document all LSP implementations", and RA outside of VSCode ends up in a no man's land of undocumented and untested integrations owned by nobody.

[flodiebold]

@kornelski As a non-VSCode user, I don't agree that RA is VSCode-centric. Yes, the reference implementation is the VSCode plugin, but, well, something needs to be. The RA team can't possibly maintain integrations for a bunch of editors no one on the team uses. If the integration for a specific editor is bad, someone from that community needs to step up to maintain it.

The other editors say "this is just one of many LSP clients, we can't possibly test and document all LSP implementations",

Maybe don't use those editors then if you want good LSP integration. My experience is that LSP has not been designed with the goal of "no per-server integration code needed in the editor at all".

I'm constantly frustrated by features that are missing from rust-analyzer

Can you give some examples of those features? (Except per-project config, which is literally already implemented)

[matklad]

FWIW, i'd love to see ./editors/helix, ./editors/emacs, ./editors/nvim in this repository. That's why it was, forever, ./editors/code and not just ./code. But that of course requires:

• someone on the team to maintain those extensions
• editor-side infrastructure to allow extensions.

My experience is that LSP has not been designed with the goal of "no per-server integration code needed in the editor at all".

Yes. This is absolutely the design. This is a very important fact: there is no LSP support directly in VS Code. There are only language-specific extensions, which happen to use the same common LSP library (that is, each extension bundles its own private copy of the library).

---

All our extras are documented here:

• https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/lsp-extensions.md
• there's "RSS feed" for updates here: Announcements: Client Changes #4604

[rzvxa]

@alibektas that's a great news. However, I can't figure out what syntax it wants. I've tried rust-analyzer.toml in the project root with:

[rust-analyzer.cargo]
features = "all"
# or
[cargo]
features = "all"

but I don't see any effect, even after restarting RA manually.

@alibektas What is the intended syntax I also have issues with setting it up

In addition to the 2 ways mentioned above, I've tried this to no avail.

cargo.features = "all"

I get this error.

invalid config value:
cargo/features: unexpected field

[lnicola]

@alibektas is something like cachePriming.enable = false supposed to work? I think assist.emitMustUse = true is the only one used in tests, and it works for me, but not the others. See also rzvxa's comment above.

[Veykril]

See #17945, right now almost none of the configs can be used in a workspace or user toml file

[lnicola]

~/.config/rust-analyzer/rust-analyzer.toml doesn't seem to get loaded in my tests (options don't take effect, and it doesn't complain about syntax errors).

[alibektas]

~/.config/rust-analyzer/rust-analyzer.toml doesn't seem to get loaded in my tests (options don't take effect, and it doesn't complain about syntax errors).

That I still need to fix. I worked on it but it is still not complete

[vaqxai]

I tried to use this. I have a workspace like this

workspace
|-crate1
|-crate2
|-crate3
|_crate4

crate 2 and 4 have a feature called "example_feature" that i want to enable for RA,
so using a workspace setting is a no go, because RA will complain that crates 1 and 3 don't have this feature
creating rust-analyzer.toml in crate 2 and 4's root and adding cargo.features = ["example_feature"] has no effect,
however if i replace it with rust-analyzer.cargo.features = ["example_feature"], RA will complain that this is an invalid key that doesn't exist. So it reads the file but when it reads a correct key it doesn't apply that? I have no machine-wide or workspace or user overrides (using VSC right now but same happens in Vim).

There is still a lot of uncertainty about the format of rust-analyzer.toml, is it the same as the JSON config? Do we exclude the rust-analyzer key? Can we get an example at least?

[alibektas]

You were right in assuming that we omit rust-analyzer prefix. I will add an example to #17058. A thorough documentation will follow as soon as we update our manual. The reason why it does not have an affect may simply be that it is a bug. I will take a look at it today and will let you know. Ok?

EDIT : Now thinking about it for a second time, the problem must be due to the fact that cargo.features is defined as workspace meaning that it has no affect when it is defined on a crate level. So we need to make it local I guess. I will think about this as I said.

[Logarithmus]

Where can I find an example of rust-analyzer.toml? Can't find any documentation whatsoever

[alibektas]

Where can I find an example of rust-analyzer.toml? Can't find any documentation whatsoever

We still don't have a dedicated documentation to it. I guess you can see #17058 or ask me if you have any questions.

[bluss]

Would it be possible for you to show an example of a valid, working rust-analyzer.toml file in a comment here? So that syntax and structure becomes clear. An example would go a long way.

[alibektas]

The first to keep in mind that rust-analyzer.toml is still in progress. You may not get the intended behavior just yet. Anything where you get something unexpected deserves a separate issue :)

rust-analyzer.toml ( a.k.a ratoml ) is a a file that follows the toml syntax. Its keys are those specified in the rust-analyzer manual, only difference being that the rust-analyzer. prefix is always omitted.

So sth like

{
      "rust_analyzer.cachePriming.enable" : true,
      "rust_analyzer.files.excludeDirs" : [ "abc" ], 
}

becomes

cachePriming.enable = true
files.excludeDirs = [ "abc" ]

One advantage of toml's syntax over that of json's is that we can group keys with mutual prefixes in a table. So sth like

{
        "rust_analyzer.highlightRelated.breakPoints.enable"  : true,
        "rust_analyzer.highlightRelated.closureCaptures.enable"  :  true,
        "rust_analyzer.highlightRelated.exitPoints.enable" : true,
        "rust_analyzer.highlightRelated.references.enable" : true,
        "rust_analyzer.highlightRelated.yieldPoints.enable"  : true,
}

can easily be turned into

[highlightRelated]
breakPoints.enable = true
closureCaptures.enable = true
exitPoints.enable = true
references.enable = true
yieldPoints.enable = true

It is a trivial thing but I still wanted to mention it :)
At this point I want to say two things : There must be many problems with the current ratoml infrastructure. It is getting better everyday but we are still not in a comfortable state with it.

Since ratoml offers a much more flexible configurability as opposed to editor config files such as settings.json in VSCode where you have a single file to configure an entire project, it was necessary to adapt rest of the codebase to this new condition. It is important to check once again the issue #17058 to see what kind of config classes we thought of. Each config key will belong to one of these classes and this property is important because it defines the domain in which a key-value pair takes affect. So if for instance a key is a workspace key, then it will only take affect in the workspace it is defined, and it can only be defined at the root of a workspace.

[csmulhern]

Using rust-analyzer 0.0.0 (a341d598d 2024-11-04), I'm unable to get a rust-analyzer.toml file to be recognized at the root of the workspace.

If I run:

cargo new example
cd example
echo "assist.emitMustUse = true" > rust-analyzer.toml

And then start my editor (Zed) with env RA_LOG=rust_analyzer=info, I see that no ratoml file is detected.

// logs
...
ratoml_file: {},
...

Are we missing resolution of ratoml files at the root of the workspace?

[alibektas]

Ok just deleted my previous comment I will check and see what's wrong. This kind of an error is ofc not supposed to have happened

[alibektas]

@csmulhern Ok so I checked it. Every is working fine (at least for this particular config key) . The reason why file names don't show up is that they are not detected at the stage where you get this debug output. Let me know if you have any other questions/simply don't agree with this :)

[csmulhern]

@csmulhern Ok so I checked it. Every is working fine (at least for this particular config key) . The reason why file names don't show up is that they are not detected at the stage where you get this debug output. Let me know if you have any other questions/simply don't agree with this :)

Thanks for looking into this.

The actual issue I'm trying to fix is with setting check.overrideCommand, and I was using the log output to validate the config was being applied. The log line that suggested ratoml_file was unset misled me into thinking the issue was with the loading of the toml file, rather than an issue with the check.overrideCommand config option being set through rust-analyzer.toml.

With the same setup as before, but with rust-analyzer.toml set to:

check.overrideCommand = ["./script.sh"]

My script is never called by flycheck, so it seems like this config option is not being applied correctly.

From the logs, you can see that cargo check continues to be used:

stderr: 2024-11-11T23:15:15.578506Z DEBUG did restart flycheck command="cd "/home/user/asdf" && RUSTUP_TOOLCHAIN="/home/user/.rustup/toolchains/stable-aarch64-apple-darwin" "/home/user/.cargo/bin/cargo" "check" "--workspace" "--message-format=json" "--manifest-path" "/home/user/Desktop/asdf/Cargo.toml" "--keep-going" "--all-targets""

1. Are there specific logging options I can use that will help validate that a rust-analyzer.toml is actually being applied to the rust-analyzer configuration?

2. Should I open a separate issue for rust-analyzer.check.overrideCommand not being settable through rust-analyzer.toml?

[alibektas]

@csmulhern Oh I see. You don't have to open a separate issue for this config key because it is already known to me and I am working on this, but there is a preliminary work to be done (see 18186 I don't want to create a link to this issue so pardon me for the inconvenience). It should take about some three weeks as the team-lead is away at the moment and he is the only other person who could actually review my PR ( PR is also WIP so you won't find anything yet). Until then I can sadly recommend you to use your editor's config file to configure rust-analyzer. I will keep you posted, ok?

Are there specific logging options I can use that will help validate that a rust-analyzer.toml is actually being applied to the rust-analyzer configuration?

Sadly we are also very poor in terms of UX/debugging for ratoml files. I will add some basic logs so that you can follow what's going on.

[csmulhern]

Completely understand that it could take some time to resolve things here; just wanted to see if this was a known issue, and if so, see if I could follow along. I've subscribed to 18186 and will get my updates there. In the meantime, using the editor config file is a good stop gap measure. Cheers!

Sadly we are also very poor in terms of UX/debugging for ratoml files. I will add some basic logs so that you can follow what's going on.

I'm sure this would be handy for root causing issues with other config options, but it's no longer critical for my use case.

I really appreciate all the help / effort here, and am excited about broader support / adoption of rust-analyzer.toml. Thanks, Ali!

[mamekoro]

My concern is that TOML does not support null.

rust-analyzer.inlayHints.maxLength (default: 25)
Maximum length for inlay hints. Set to null to have an unlimited length.

https://rust-analyzer.github.io/manual.html#rust-analyzer.inlayHints.maxLength

How can I set rust-analyzer.inlayHints.maxLength to null?