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.

• [x] 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.

[Veykril]

https://github.com/rust-lang/rust-analyzer/pull/17058 will implement the core features here, there are still some issues with it (the user config is not working correctly yet), as well some restrictions with crate specific configs due to architecture reasons (they shouldn't really be noticeably in most cases). A lot of configs are also still missing from it and the diagnostics UX (when an invalid config is supplied) is really bad. All of that will be resolved in the near or far future (time will tell).

[!IMPORTANT]
We don't promise any stability with this feature yet, any configs exposed may be removed again, the ordering may change etc.

Once the PR lands (should today), this issue will be used to track any updates on the feature.

[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 :wave: 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: https://github.com/rust-lang/rust-analyzer/issues/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 https://github.com/rust-lang/rust-analyzer/pull/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.