polkadot_sdk_docs/reference_docs/development_environment_advice.rs
1//! # Development Environment Advice
2//!
3//! Large Rust projects are known for sometimes long compile times and sluggish dev tooling, and
4//! polkadot-sdk is no exception.
5//!
6//! This page contains some advice to improve your workflow when using common tooling.
7//!
8//! ## Rust Analyzer Configuration
9//!
10//! [Rust Analyzer](https://rust-analyzer.github.io/) is the defacto [LSP](https://langserver.org/) for Rust. Its default
11//! settings are fine for smaller projects, but not well optimised for polkadot-sdk.
12//!
13//! Below is a suggested configuration for VSCode or any VSCode-based editor like Cursor:
14//!
15//! ```json
16//! {
17//! // Use a separate target dir for Rust Analyzer. Helpful if you want to use Rust
18//! // Analyzer and cargo on the command line at the same time,
19//! // at the expense of duplicating build artifacts.
20//! "rust-analyzer.cargo.targetDir": "target/vscode-rust-analyzer",
21//! // Improve stability
22//! "rust-analyzer.server.extraEnv": {
23//! "CHALK_OVERFLOW_DEPTH": "100000000",
24//! "CHALK_SOLVER_MAX_SIZE": "10000000"
25//! },
26//! // Check feature-gated code
27//! "rust-analyzer.cargo.features": "all",
28//! "rust-analyzer.cargo.extraEnv": {
29//! // Skip building WASM, there is never need for it here
30//! "SKIP_WASM_BUILD": "1"
31//! },
32//! // Don't expand some problematic proc_macros
33//! "rust-analyzer.procMacro.ignored": {
34//! "async-trait": ["async_trait"],
35//! "napi-derive": ["napi"],
36//! "async-recursion": ["async_recursion"],
37//! "async-std": ["async_std"]
38//! },
39//! // Use nightly formatting.
40//! // See the polkadot-sdk CI job that checks formatting for the current version used in
41//! // polkadot-sdk.
42//! "rust-analyzer.rustfmt.extraArgs": ["+nightly-2024-04-10"],
43//! }
44//! ```
45//!
46//! and the same in Lua for `neovim/nvim-lspconfig`:
47//!
48//! ```lua
49//! ["rust-analyzer"] = {
50//! rust = {
51//! # Use a separate target dir for Rust Analyzer. Helpful if you want to use Rust
52//! # Analyzer and cargo on the command line at the same time.
53//! analyzerTargetDir = "target/nvim-rust-analyzer",
54//! },
55//! server = {
56//! # Improve stability
57//! extraEnv = {
58//! ["CHALK_OVERFLOW_DEPTH"] = "100000000",
59//! ["CHALK_SOLVER_MAX_SIZE"] = "100000000",
60//! },
61//! },
62//! cargo = {
63//! # Check feature-gated code
64//! features = "all",
65//! extraEnv = {
66//! # Skip building WASM, there is never need for it here
67//! ["SKIP_WASM_BUILD"] = "1",
68//! },
69//! },
70//! procMacro = {
71//! # Don't expand some problematic proc_macros
72//! ignored = {
73//! ["async-trait"] = { "async_trait" },
74//! ["napi-derive"] = { "napi" },
75//! ["async-recursion"] = { "async_recursion" },
76//! ["async-std"] = { "async_std" },
77//! },
78//! },
79//! rustfmt = {
80//! # Use nightly formatting.
81//! # See the polkadot-sdk CI job that checks formatting for the current version used in
82//! # polkadot-sdk.
83//! extraArgs = { "+nightly-2024-04-10" },
84//! },
85//! },
86//! ```
87//!
88//! Alternatively for neovim, if you are using [Rustaceanvim](https://github.com/mrcjkb/rustaceanvim),
89//! you can achieve the same configuring `rust-analyzer` via `rustaceanvim` as follows:
90//! ```lua
91//! return {
92//! {
93//! "mrcjkb/rustaceanvim",
94//! opts = {
95//! server = {
96//! default_settings = {
97//! ["rust-analyzer"] = {
98//! // put the same config as for nvim-lspconfig here
99//! },
100//! },
101//! },
102//! },
103//! },
104//! }
105//! ```
106//!
107//! Similarly for Zed, you can replicate the same VSCode configuration in
108//! `~/.config/zed/settings.json` as follows:
109//! ```json
110//! "lsp": {
111//! "rust-analyzer": {
112//! "initialization_options": {
113//! // same config as for VSCode for rust, cargo, procMacros, ...
114//! }
115//! }
116//! },
117//! ```
118//!
119//! In general, refer to your favorite editor / IDE's documentation to properly configure
120//! `rust-analyzer` as language server.
121//! For the full set of configuration options see <https://rust-analyzer.github.io/manual.html#configuration>.
122//!
123//! ## Cargo Usage
124//!
125//! ### Using `--package` (a.k.a. `-p`)
126//!
127//! polkadot-sdk is a monorepo containing many crates. When you run a cargo command without
128//! `-p`, you will almost certainly compile crates outside of the scope you are working.
129//!
130//! Instead, you should identify the name of the crate you are working on by checking the `name`
131//! field in the closest `Cargo.toml` file. Then, use `-p` with your cargo commands to only compile
132//! that crate.
133//!
134//! ### `SKIP_WASM_BUILD=1` environment variable
135//!
136//! When cargo touches a runtime crate, by default it will also compile the WASM binary,
137//! approximately doubling the compilation time.
138//!
139//! The WASM binary is usually not needed, especially when running `check` or `test`. To skip the
140//! WASM build, set the `SKIP_WASM_BUILD` environment variable to `1`. For example:
141//! `SKIP_WASM_BUILD=1 cargo check -p frame-support`.
142//!
143//! ### Cargo Remote
144//!
145//! Warning: cargo remote by default doesn't transfer hidden files to the remote machine. But hidden
146//! files can be useful, e.g. for sqlx usage. On the other hand using `--transfer-hidden` flag will
147//! transfer `.git` which is big.
148//!
149//! If you have a powerful remote server available, you may consider using
150//! [cargo-remote](https://github.com/sgeisler/cargo-remote) to execute cargo commands on it,
151//! freeing up local resources for other tasks like `rust-analyzer`.
152//!
153//! When using `cargo-remote`, you can configure your editor to perform the the typical
154//! "check-on-save" remotely as well. The configuration for VSCode (or any VSCode-based editor like
155//! Cursor) is as follows:
156//!
157//! ```json
158//! {
159//! "rust-analyzer.cargo.buildScripts.overrideCommand": [
160//! "cargo",
161//! "remote",
162//! "--build-env",
163//! "SKIP_WASM_BUILD=1",
164//! "--",
165//! "check",
166//! "--message-format=json",
167//! "--all-targets",
168//! "--all-features",
169//! "--target-dir=target/rust-analyzer"
170//! ],
171//! "rust-analyzer.check.overrideCommand": [
172//! "cargo",
173//! "remote",
174//! "--build-env",
175//! "SKIP_WASM_BUILD=1",
176//! "--",
177//! "check",
178//! "--workspace",
179//! "--message-format=json",
180//! "--all-targets",
181//! "--all-features",
182//! "--target-dir=target/rust-analyzer"
183//! ],
184//! }
185//! ```
186//!
187//! and the same in Lua for `neovim/nvim-lspconfig`:
188//!
189//! ```lua
190//! ["rust-analyzer"] = {
191//! cargo = {
192//! buildScripts = {
193//! overrideCommand = {
194//! "cargo",
195//! "remote",
196//! "--build-env",
197//! "SKIP_WASM_BUILD=1",
198//! "--",
199//! "check",
200//! "--message-format=json",
201//! "--all-targets",
202//! "--all-features",
203//! "--target-dir=target/rust-analyzer"
204//! },
205//! },
206//! },
207//! check = {
208//! overrideCommand = {
209//! "cargo",
210//! "remote",
211//! "--build-env",
212//! "SKIP_WASM_BUILD=1",
213//! "--",
214//! "check",
215//! "--workspace",
216//! "--message-format=json",
217//! "--all-targets",
218//! "--all-features",
219//! "--target-dir=target/rust-analyzer"
220//! },
221//! },
222//! },
223//! ```