referrerpolicy=no-referrer-when-downgrade

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//! ```