From 45f4d9a2b91771d8fad6c51ad9858b324ec664a4 Mon Sep 17 00:00:00 2001
From: Liam Aharon <liam.aharon@hotmail.com>
Date: Fri, 29 Dec 2023 16:24:26 +0400
Subject: [PATCH] Development Environment Advice Reference Doc (#2759)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Closes https://github.com/paritytech/polkadot-sdk-docs/issues/63
---------
Co-authored-by: Dónal Murray <donal.murray@parity.io>
Co-authored-by: PG Herveou <pgherveou@gmail.com>
Co-authored-by: joe petrowski <25483142+joepetrowski@users.noreply.github.com>
---
.../development_environment_advice.rs | 113 ++++++++++++++++++
docs/sdk/src/reference_docs/mod.rs | 3 +
2 files changed, 116 insertions(+)
create mode 100644 docs/sdk/src/reference_docs/development_environment_advice.rs
diff --git a/docs/sdk/src/reference_docs/development_environment_advice.rs b/docs/sdk/src/reference_docs/development_environment_advice.rs
new file mode 100644
index 00000000000..27dd4638604
--- /dev/null
+++ b/docs/sdk/src/reference_docs/development_environment_advice.rs
@@ -0,0 +1,113 @@
+//! # Development Environment Advice
+//!
+//! Large Rust projects are known for sometimes long compile times and sluggish dev tooling, and
+//! polkadot-sdk is no exception.
+//!
+//! This page contains some advice to improve your workflow when using common tooling.
+//!
+//! ## Rust Analyzer Configuration
+//!
+//! [Rust Analyzer](https://rust-analyzer.github.io/) is the defacto [LSP](https://langserver.org/) for Rust. Its default
+//! settings are fine for smaller projects, but not well optimised for polkadot-sdk.
+//!
+//! Below is a suggested configuration for VSCode:
+//!
+//! ```json
+//! {
+//! // Use a separate target dir for Rust Analyzer. Helpful if you want to use Rust
+//! // Analyzer and cargo on the command line at the same time.
+//! "rust-analyzer.rust.analyzerTargetDir": "target/vscode-rust-analyzer",
+//! // Improve stability
+//! "rust-analyzer.server.extraEnv": {
+//! "CHALK_OVERFLOW_DEPTH": "100000000",
+//! "CHALK_SOLVER_MAX_SIZE": "10000000"
+//! },
+//! // Check feature-gated code
+//! "rust-analyzer.cargo.features": "all",
+//! "rust-analyzer.cargo.extraEnv": {
+//! // Skip building WASM, there is never need for it here
+//! "SKIP_WASM_BUILD": "1"
+//! },
+//! // Don't expand some problematic proc_macros
+//! "rust-analyzer.procMacro.ignored": {
+//! "async-trait": ["async_trait"],
+//! "napi-derive": ["napi"],
+//! "async-recursion": ["async_recursion"],
+//! "async-std": ["async_std"]
+//! },
+//! // Use nightly formatting.
+//! // See the polkadot-sdk CI job that checks formatting for the current version used in
+//! // polkadot-sdk.
+//! "rust-analyzer.rustfmt.extraArgs": ["+nightly-2023-11-01"],
+//! }
+//! ```
+//!
+//! and the same in Lua for `neovim/nvim-lspconfig`:
+//!
+//! ```lua
+//! ["rust-analyzer"] = {
+//! rust = {
+//! # Use a separate target dir for Rust Analyzer. Helpful if you want to use Rust
+//! # Analyzer and cargo on the command line at the same time.
+//! analyzerTargetDir = "target/nvim-rust-analyzer",
+//! },
+//! server = {
+//! # Improve stability
+//! extraEnv = {
+//! ["CHALK_OVERFLOW_DEPTH"] = "100000000",
+//! ["CHALK_SOLVER_MAX_SIZE"] = "100000000",
+//! },
+//! },
+//! cargo = {
+//! # Check feature-gated code
+//! features = "all",
+//! extraEnv = {
+//! # Skip building WASM, there is never need for it here
+//! ["SKIP_WASM_BUILD"] = "1",
+//! },
+//! },
+//! procMacro = {
+//! # Don't expand some problematic proc_macros
+//! ignored = {
+//! ["async-trait"] = { "async_trait" },
+//! ["napi-derive"] = { "napi" },
+//! ["async-recursion"] = { "async_recursion" },
+//! ["async-std"] = { "async_std" },
+//! },
+//! },
+//! rustfmt = {
+//! # Use nightly formatting.
+//! # See the polkadot-sdk CI job that checks formatting for the current version used in
+//! # polkadot-sdk.
+//! extraArgs = { "+nightly-2023-11-01" },
+//! },
+//! },
+//! ```
+//!
+//! For the full set of configuration options see <https://rust-analyzer.github.io/manual.html#configuration>.
+//!
+//! ## Cargo Usage
+//!
+//! ### Using `--package` (a.k.a. `-p`)
+//!
+//! polkadot-sdk is a monorepo containing many crates. When you run a cargo command without
+//! `-p`, you will almost certainly compile crates outside of the scope you are working.
+//!
+//! Instead, you should identify the name of the crate you are working on by checking the `name`
+//! field in the closest `Cargo.toml` file. Then, use `-p` with your cargo commands to only compile
+//! that crate.
+//!
+//! ### `SKIP_WASM_BUILD=1` environment variable
+//!
+//! When cargo touches a runtime crate, by default it will also compile the WASM binary,
+//! approximately doubling the compilation time.
+//!
+//! The WASM binary is usually not needed, especially when running `check` or `test`. To skip the
+//! WASM build, set the `SKIP_WASM_BUILD` environment variable to `1`. For example:
+//! `SKIP_WASM_BUILD=1 cargo check -p frame-support`.
+//!
+//! ### Cargo Remote
+//!
+//! If you have a powerful remote server available, you may consider using
+//! [cargo-remote](https://github.com/sgeisler/cargo-remote) to execute cargo commands on it,
+//! freeing up local resources for other tasks like `rust-analyzer`.
diff --git a/docs/sdk/src/reference_docs/mod.rs b/docs/sdk/src/reference_docs/mod.rs
index 44284394000..c16122ee428 100644
--- a/docs/sdk/src/reference_docs/mod.rs
+++ b/docs/sdk/src/reference_docs/mod.rs
@@ -69,6 +69,9 @@ pub mod frame_system_accounts;
/// Learn about the currency-related abstractions provided in FRAME.
pub mod frame_currency;
+/// Advice for configuring your development environment for Substrate development.
+pub mod development_environment_advice;
+
/// Learn about benchmarking and weight.
// TODO: @shawntabrizi @ggwpez https://github.com/paritytech/polkadot-sdk-docs/issues/50
pub mod frame_benchmarking_weight;
--
GitLab