From e4bca8873616aa73834b8225152e403872409198 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20Thei=C3=9Fen?= Date: Thu, 22 Oct 2020 20:17:42 +0200 Subject: [PATCH 1/5] llvm is no longer required I don't know why or when that happended but I do not have it installed and everything works for me. --- docs/knowledgebase/getting-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/knowledgebase/getting-started/index.md b/docs/knowledgebase/getting-started/index.md index 4bca7015c9..fa02ddca73 100644 --- a/docs/knowledgebase/getting-started/index.md +++ b/docs/knowledgebase/getting-started/index.md @@ -30,7 +30,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 From 3dbca017dc12a62a5c3ad5b92cdd21ece1428923 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20Thei=C3=9Fen?= Date: Thu, 22 Oct 2020 20:21:53 +0200 Subject: [PATCH 2/5] Add some more comments to the source command --- docs/knowledgebase/getting-started/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/knowledgebase/getting-started/index.md b/docs/knowledgebase/getting-started/index.md index fa02ddca73..efd96c694f 100644 --- a/docs/knowledgebase/getting-started/index.md +++ b/docs/knowledgebase/getting-started/index.md @@ -65,7 +65,8 @@ 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 ``` From e99718b41f50a7eb7eb9f4e12617e1685d4dd045 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20Thei=C3=9Fen?= Date: Thu, 22 Oct 2020 20:54:15 +0200 Subject: [PATCH 3/5] Rework how toolchains are explained --- docs/knowledgebase/getting-started/index.md | 60 +++++++++++++-------- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/docs/knowledgebase/getting-started/index.md b/docs/knowledgebase/getting-started/index.md index efd96c694f..f81a7e565b 100644 --- a/docs/knowledgebase/getting-started/index.md +++ b/docs/knowledgebase/getting-started/index.md @@ -81,21 +81,35 @@ 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. +compile 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- @@ -103,39 +117,39 @@ 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 in order to do so. If that version is incompatible +you can override that decision by setting the `WASM_BUILD_TOOLCHAIN` environment variable +when building the project: ```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 +as it should be. + #### 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 tight to a specific version and will be updated, just as the +`stable` toolchain, when you issue: ```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 a new feature of the Rust compiler. + ## Test Your Set-Up The best way to ensure that you have successfully prepared a computer for Substrate development is From d1b922781d808147525cca08c10f779fb51f7fd7 Mon Sep 17 00:00:00 2001 From: Addie Wagenknecht Date: Fri, 23 Oct 2020 11:01:08 +0200 Subject: [PATCH 4/5] Update index.md --- docs/knowledgebase/getting-started/index.md | 48 +++++++++------------ 1 file changed, 21 insertions(+), 27 deletions(-) diff --git a/docs/knowledgebase/getting-started/index.md b/docs/knowledgebase/getting-started/index.md index f81a7e565b..6e609cfb0e 100644 --- a/docs/knowledgebase/getting-started/index.md +++ b/docs/knowledgebase/getting-started/index.md @@ -3,24 +3,19 @@ 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 +#### MacOS Open the Terminal application and execute the following commands: @@ -59,7 +54,7 @@ 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 @@ -80,13 +75,13 @@ 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 substrate compatible runtimes to Wasm. +[`nightly` builds](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) to allow +compiled substrate compatible runtimes to Wasm. #### Rust Nightly Toolchain 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. +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: @@ -97,8 +92,8 @@ 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 +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 @@ -117,18 +112,17 @@ rustup target add wasm32-unknown-unknown --toolchain nightly- #### Specifying Nightly Version -When a Substrate-based project builds its included runtime it picks the latest -installed nightly version by default in order to do so. If that version is incompatible +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: +when building the project by using the following command: ```bash 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 -as it should be. +be compiled with your default toolchain which is usually the latest installed stable toolchain. #### Latest Nightly @@ -140,15 +134,15 @@ rustup install nightly rustup target add wasm32-unknown-unknown --toolchain nightly ``` -This toolchain is not tight to a specific version and will be updated, just as the -`stable` toolchain, when you issue: +This toolchain is not tied to a specific version and will be updated just as the +`stable` toolchain: ```bash rustup update ``` **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. +codebase depends on the most recent version of the Rust compiler. ## Test Your Set-Up From 752fc549b98bfd29a57c0f1947aef08099bf01b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20Thei=C3=9Fen?= Date: Fri, 23 Oct 2020 11:48:21 +0200 Subject: [PATCH 5/5] MacOS -> macOS --- docs/knowledgebase/getting-started/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/knowledgebase/getting-started/index.md b/docs/knowledgebase/getting-started/index.md index 6e609cfb0e..463f7716a1 100644 --- a/docs/knowledgebase/getting-started/index.md +++ b/docs/knowledgebase/getting-started/index.md @@ -6,16 +6,16 @@ This page will guide you through the steps needed to prepare a computer for Subs 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 +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 optimized for 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 the terminal to demonstrate how to interact with Substrate from the command line. -#### MacOS +#### macOS Open the Terminal application and execute the following commands: