diff --git a/docs/knowledgebase/getting-started/index.md b/docs/knowledgebase/getting-started/index.md index 4bca7015c9..463f7716a1 100644 --- a/docs/knowledgebase/getting-started/index.md +++ b/docs/knowledgebase/getting-started/index.md @@ -3,22 +3,17 @@ title: Installation --- This page will guide you through the steps needed to prepare a computer for Substrate development. -Since Substrate is built with [the Rust programming language](https://www.rust-lang.org/), the first -thing you will need to do is prepare the computer for Rust development - these steps will vary based -on the computer's operating system. Then, you can use the helpful utilities from the Rust toolchain -to configure the Rust development environment - these steps will be the same for all the -(Unix-based) operating systems discussed on this page. - -## Operating System-Dependent Set-Up - -Follow the steps for your computer's operating system before installing and configuring the Rust -toolchain. +As Substrate is built with [the Rust programming language](https://www.rust-lang.org/), the first +thing you will need to do is prepare the development enviroment, these steps will vary based +on the computer's operating system. You can utilize helpful utilities from the Rust toolchain +to configure the Rust development environment. Note that these steps will be the same for all +Unix-based operating systems discussed on this page. ### Unix-Based Operating Systems -Substrate development is easiest on Unix-based operating systems, like macOS or Linux. The examples +Substrate development is optimized for Unix-based operating systems like macOS or Linux. The examples in the Substrate [Tutorials](../../../../tutorials) and [Recipes](https://substrate.dev/recipes/) -use Unix-style terminals to demonstrate how to interact with Substrate from the command line. +use the terminal to demonstrate how to interact with Substrate from the command line. #### macOS @@ -30,7 +25,7 @@ Open the Terminal application and execute the following commands: # Make sure Homebrew is up-to-date and install some dependencies brew update -brew install openssl cmake llvm +brew install openssl cmake ``` #### Ubuntu/Debian @@ -59,13 +54,14 @@ Please refer to the separate [guide for Windows users](windows-users.md). ## Rust Developer Environment -This guide uses [`rustup`](https://rustup.rs/) to help manage the Rust toolchain; first, install and +This guide uses [`rustup`](https://rustup.rs/) to help manage the Rust toolchain. First install and configure `rustup`: ```bash # Install curl https://sh.rustup.rs -sSf | sh -# Configure +# Add the rust compiler and other tools to your PATH. +# Make sure to add this to your shell startup script, too. source ~/.cargo/env ``` @@ -79,22 +75,36 @@ rustup default stable Substrate uses [WebAssembly](https://webassembly.org/) (Wasm) to produce portable blockchain runtimes. You will need to configure your Rust compiler to use -[`nightly` builds](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) to allow you to -compile Rust code to the Wasm target. +[`nightly` builds](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) to allow +compiled substrate compatible runtimes to Wasm. #### Rust Nightly Toolchain -Developers that are building _with_ Substrate (as opposed to the developers building Substrate -_itself_) should use a specific Rust nightly version that is known to be compatible with the version -of Substrate they are using. Use Rustup to install the correct nightly: +Because the nightly toolchain is a moving target and receives daily changes the chance +that some of them break the substrate build from time to time is non-negligible. + +Therefore it is advised to use a fixed nightly version rather than the latest one to +build the runtime. You can install a specific version using this command: ```bash rustup install nightly- ``` +--- +**NOTE** +Due to a regression in the rust compiler, using the newest rust nightly for compiling +the runtime will result in compilation errors. Therefore, it is advised to use the +following version until this issue is resolved: + +```bash +rustup install nightly-2010-10-06 +``` + +--- + #### Wasm Toolchain -Now, configure the nightly version to work with the Wasm compilation target: +Now, configure the choosen nightly version to work with the Wasm compilation target: ```bash rustup target add wasm32-unknown-unknown --toolchain nightly- @@ -102,39 +112,38 @@ rustup target add wasm32-unknown-unknown --toolchain nightly- #### Specifying Nightly Version -If you are working with a Substrate-based project that does not include a toolchain file, you can -use the Rust build and package manager, [Cargo](https://doc.rust-lang.org/cargo/), to specify a -nightly version: +When a Substrate based project builds its included runtime it picks the latest +installed nightly version by default. If the nightly version is incompatible +you can override that decision by setting the `WASM_BUILD_TOOLCHAIN` environment variable +when building the project by using the following command: ```bash -cargo +nightly- ... +WASM_BUILD_TOOLCHAIN=nightly- cargo build ``` +Note that this builds only the runtime with the specified toolchain. The rest of project will +be compiled with your default toolchain which is usually the latest installed stable toolchain. + #### Latest Nightly -Developers that are building Substrate _itself_ should always uses the latest version of Rust stable -and nightly for compilation. To ensure your Rust compiler is always up to date, you should run: +If you want to build the runtime with the latest nightly compiler which should **generally** be +possible you can install the unspecific `nightly` toolchain: ```bash -rustup update -rustup update nightly +rustup install nightly rustup target add wasm32-unknown-unknown --toolchain nightly ``` -**It may be necessary to occasionally rerun `rustup update`** if a change in the upstream Substrate -codebase depends on a new feature of the Rust compiler. - -#### Downgrading Rust Nightly - -If your computer is configured to use the latest Rust nightly and you would like to downgrade to a -specific nightly version, follow these steps: +This toolchain is not tied to a specific version and will be updated just as the +`stable` toolchain: ```bash -rustup uninstall nightly -rustup install nightly- -rustup target add wasm32-unknown-unknown --toolchain nightly- +rustup update ``` +**It may be necessary to occasionally rerun `rustup update`** if a change in the upstream Substrate +codebase depends on the most recent version of the Rust compiler. + ## Test Your Set-Up The best way to ensure that you have successfully prepared a computer for Substrate development is