#
pezkuwi_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//! pezkuwi-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 pezkuwi-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 pezkuwi-sdk CI job that checks formatting for the current version used in
    41//!   // pezkuwi-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 pezkuwi-sdk CI job that checks formatting for the current version used in
    82//!     # pezkuwi-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//! pezkuwi-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 pezframe-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//! ```