Updates to installation guide (#772)

Author: Dan Forbes

docs/knowledgebase/getting-started/index.md

@@ -3,41 +3,42 @@ title: Installation
 ---
 
 This page will guide you through the steps needed to prepare a computer for Substrate development.
-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. 
+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. Once Rust is configured, you will use its toolchains to interact
+with Rust projects; the commands for Rust's toolchains will be the same for all supported,
+Unix-based operating systems.
 
-### Unix-Based Operating Systems
+## Unix-Based Operating Systems
 
-Substrate development is optimized for Unix-based operating systems like macOS or Linux. The examples
+Substrate development is easiest on 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.
+use Unix-style terminals to demonstrate how to interact with Substrate from the command line.
 
-#### macOS
+### macOS
 
 Open the Terminal application and execute the following commands:
 
 ```bash
 # Install Homebrew if necessary https://brew.sh/
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
 
-# Make sure Homebrew is up-to-date and install some dependencies
+# Make sure Homebrew is up-to-date, install openssl and cmake
 brew update
 brew install openssl cmake
 ```
 
-#### Ubuntu/Debian
+### Ubuntu/Debian
 
-Use your favorite terminal shell to execute the following commands:
+Use a terminal shell to execute the following commands:
 
 ```bash
 sudo apt update
 # May prompt for location information
 sudo apt install -y cmake pkg-config libssl-dev git build-essential clang libclang-dev curl
 ```
 
-#### Arch Linux
+### Arch Linux
 
 Run these commands from a terminal:
 
@@ -47,7 +48,7 @@ export OPENSSL_LIB_DIR="/usr/lib/openssl-1.0"
 export OPENSSL_INCLUDE_DIR="/usr/include/openssl-1.0"
 ```
 
-### Windows
+## Windows
 
 Please refer to the separate [guide for Windows users](windows-users.md).
 
@@ -59,8 +60,7 @@ configure `rustup`:
 ```bash
 # Install
 curl https://sh.rustup.rs -sSf | sh
-# Add the rust compiler and other tools to your PATH.
-# Make sure to add this to your shell startup script, too.
+# Configure
 source ~/.cargo/env
 ```
 
@@ -74,119 +74,76 @@ 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
-compiled substrate compatible runtimes to Wasm.
+[`nightly` builds](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) to allow you to
+compile Substrate runtime code to the Wasm target.
 
 #### 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.
-
-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:
+Developers building with Substrate should use a specific Rust nightly version that is known to be
+compatible with the version of Substrate they are using; this version will vary from project to
+project and different projects may use different mechanisms to communicate this version to
+developers. For instance, the Polkadot client specifies this information in its
+[release notes](https://github.com/paritytech/polkadot/releases). The Substrate Node Template uses
+an
+[init script](https://github.com/substrate-developer-hub/substrate-node-template/blob/master/scripts/init.sh)
+and
+[Makefile](https://github.com/substrate-developer-hub/substrate-node-template/blob/master/Makefile)
+to specify the Rust nightly version and encapsulate the following steps. Use Rustup to install the
+correct nightly:
 
 ```bash
 rustup install nightly-<yyyy-MM-dd>
 ```
 
----
-**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-2020-10-06
-```
-
----
-
 #### Wasm Toolchain
 
-Now, configure the choosen nightly version to work with the Wasm compilation target:
+Now, configure the nightly version to work with the Wasm compilation target:
 
 ```bash
 rustup target add wasm32-unknown-unknown --toolchain nightly-<yyyy-MM-dd>
 ```
 
 #### Specifying 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:
+Use the `WASM_BUILD_TOOLCHAIN` environment variable to specify the Rust nightly version a Substrate
+project should use for Wasm compilation:
 
 ```bash
-WASM_BUILD_TOOLCHAIN=nightly-<yyyy-MM-dd> cargo build
+WASM_BUILD_TOOLCHAIN=nightly-<yyyy-MM-dd> cargo build --release
 ```
 
-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.
+Note that this only builds _the runtime_ with the specified nightly. The rest of project will be
+compiled with the default toolchain, i.e. the latest installed stable toolchain.
 
-#### Latest Nightly
+#### Latest Nightly for Substrate `master`
 
-If you want to build the runtime with the latest nightly compiler which should **generally** be
-possible you can install the unspecific `nightly` toolchain:
+Developers that are building Substrate _itself_ should always use the latest bug-free versions of
+Rust stable and nightly. This is because the Substrate codebase follows the tip of Rust nightly,
+which means that changes in Substrate often depend on upstream changes in the Rust nightly compiler.
+To ensure your Rust compiler is always up to date, you should run:
 
 ```bash
-rustup install nightly
+rustup update
+rustup update nightly
 rustup target add wasm32-unknown-unknown --toolchain nightly
 ```
 
-This toolchain is not tied to a specific version and will be updated just as the
-`stable` toolchain:
+**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.
 
-```bash
-rustup update
-```
+#### Downgrading Rust Nightly
 
-## Tips
+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:
 
-**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.
+```sh
+rustup uninstall nightly
+rustup install nightly-<yyyy-MM-dd>
+rustup target add wasm32-unknown-unknown --toolchain nightly-<yyyy-MM-dd>
+```
 
 ## Test Your Set-Up
 
 The best way to ensure that you have successfully prepared a computer for Substrate development is
 to follow the steps in our first tutorial,
 [Create Your First Substrate Chain](../../tutorials/create-your-first-substrate-chain/).
-
-## Build with Nix shell
-
-Nix is a package manager for many different types of projects, including those based on Rust. Using Nix makes developers confident that the compilation output of their substrate-based projects is reliable and reproducible. Find more benefits on the [Nix website] (https://nixos.org/).
-
-### Steps to use Nix shell
-
-#### Install Nix
-
-Run the following command on a Unix based operating system:
-```shell
-sh <(curl -L https://nixos.org/nix/install) --daemon
-```
-
-#### Verify that Nix was properly installed
-
-```shell
-nix-env --version
-```
-
-You should see an output like: `nix-env (Nix) 2.3.7`.
-
-#### How to use
-
-If you are using `substrate` or `substrate-node-template`, the `shell.nix` file should already be in the project's root directory.
-
-```shell
-cd substrate-node-template # or substrate
-
-nix-shell # start the nix shell environment by using dependencies in file `shell.nix`, it may take some time if this's your first time.
-```
-
-#### Run cargo commands in the nix shell
-
-
-```shell
-cargo build --release # build the project
-
-./target/release/node-template # run the compiled binary
-```

docs/tutorials/add-a-pallet/import-a-pallet.md

@@ -170,5 +170,5 @@ error[E0425]: cannot find function `memory_new` in module `sandbox`
 Before moving on, check that the new dependencies resolve correctly by running:
 
 ```bash
-cargo check -p node-template-runtime
+SKIP_WASM_BUILD=1 cargo check -p node-template-runtime
 ```

docs/tutorials/add-a-pallet/use-a-pallet.md

@@ -6,7 +6,7 @@ Now you are ready to compile and run your node that has been enhanced with nickn
 from the Nicks pallet. Compile the node in release mode with:
 
 ```bash
-cargo build --release
+WASM_BUILD_TOOLCHAIN=nightly-2020-10-05 cargo build --release
 ```
 
 If the build fails, go back to the previous section and make sure you followed all the steps

docs/tutorials/add-contracts-pallet.md

@@ -168,7 +168,7 @@ std = [
 Now is a good time to check that everything compiles correctly so far with:
 
 ```bash
-cargo check
+SKIP_WASM_BUILD=1 cargo check
 ```
 
 ## Adding the Contracts Pallet
@@ -286,7 +286,7 @@ should compile, the entire node will not (yet). So we will use this command to c
 runtime.
 
 ```bash
-cargo check -p node-template-runtime
+SKIP_WASM_BUILD=1 cargo check -p node-template-runtime
 ```
 
 ### Exposing The Contracts API
@@ -381,7 +381,7 @@ impl_runtime_apis! {
 This is another good time to check that your runtime compiles correctly so far.
 
 ```bash
-cargo check -p node-template-runtime
+SKIP_WASM_BUILD=1 cargo check -p node-template-runtime
 ```
 
 ## Updating the Outer Node
@@ -499,7 +499,7 @@ Now you are ready to compile and run your contract-capable node. Compile the nod
 with
 
 ```bash
-cargo build --release
+WASM_BUILD_TOOLCHAIN=nightly-2020-10-05 cargo build --release
 ```
 
 Now launch the executable you just built by running this command

docs/tutorials/build-a-dapp/pallet.md

@@ -300,7 +300,7 @@ file, you should be able to recompile your node without warning or error. Run th
 root directory of the `substrate-node-template` repository to build and run the node:
 
 ```bash
-cargo run -- --dev --tmp
+WASM_BUILD_TOOLCHAIN=nightly-2020-10-05 cargo run --release -- --dev --tmp
 ```
 
 Now it is time to interact with our new Proof of Existence pallet!

docs/tutorials/build-permission-network/launch-network.md

@@ -5,7 +5,7 @@ title: Launch our permissioned network
 Before even starting a node, let's make sure everything is compiled for our project.
 
 ```shell
-cargo build --release
+WASM_BUILD_TOOLCHAIN=nightly-2020-10-05 cargo build --release
 ```
 
 In this part, we'll launch 4 nodes, include 3 well known nodes and 1 normal node. Here are the node keys and peer ids that are used in this tutorial.

docs/tutorials/create-a-pallet.md

@@ -83,7 +83,7 @@ You should be able to successfully check the Substrate pallet template with:
 
 ```bash
 cd test-pallet
-cargo check
+SKIP_WASM_BUILD=1 cargo check
 ```
 
 ### Your Pallet's `std` Feature
@@ -148,7 +148,7 @@ sp-core = { default-features = false, version = '2.0.0' }
 You can confirm that the tests in the Substrate pallet template pass with:
 
 ```bash
-cargo test
+SKIP_WASM_BUILD=1 cargo test
 ```
 
 When updating this pallet to include your own custom logic, you will likely add dependencies of your
@@ -216,7 +216,7 @@ Make sure you're back in the node template's root directory, then compile the no
 development mode with the following command:
 
 ```bash
-cargo run -- --dev --tmp
+WASM_BUILD_TOOLCHAIN=nightly-2020-10-05 cargo run --release -- --dev --tmp
 ```
 
 Now, start the

docs/tutorials/create-your-first-substrate-chain/setup.md

@@ -14,36 +14,11 @@ You will probably need to do some set-up to prepare your computer for Substrate
 
 ### Substrate Development
 
-If you are using a Unix-based machine (Linux, MacOS), we have created a simple one-liner to help you
-set up your computer:
-
-```bash
-curl https://getsubstrate.io -sSf | bash -s -- --fast
-```
-
-> If you did not have Rust installed prior to running this script, make sure to restart your
-> terminal before continuing.
-
-<details>
-<summary>Learn what this script does.</summary>
-
-> You can view the source code for this script by visiting
-> [https://getsubstrate.io](https://getsubstrate.io) in your browser.
-
-It will automatically install:
-
-- [CMake](https://cmake.org/install/)
-- [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)
-- [OpenSSL](https://www.openssl.org/)
-- [Git](https://git-scm.com/downloads)
-- [Rust](https://www.rust-lang.org/tools/install)
-
-</details>
-
-If you are using Windows and do not have the
-[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10), the
-process is a bit harder, but well documented
-[here](../../knowledgebase/getting-started/windows-users).
+Refer to the [official Installation guide](../../knowledgebase/getting-started/). Since this
+tutorial uses the Node Template, which includes configuration files and scripts for initializing and
+interacting with it, it's not necessary to complete all the steps from the Installation guide. After
+`rustup` has been installed and configured, and you've configured the Rust toolchain to default to
+the latest stable version you can return to these steps.
 
 ## Compiling Substrate
 
@@ -59,23 +34,13 @@ Template, which serves as a good starting point for building on Substrate.
 2. Initialize your WebAssembly build environment
 
    ```bash
-   # Load settings into the current shell script if you can't use rustup command
-   # If you've run this before, you don't need to run it again. But doing so is harmless.
-   source ~/.cargo/env
-
-   # Update Rust
-   rustup update nightly
-   rustup update stable
-
-   # Add Wasm target
-   rustup target add wasm32-unknown-unknown --toolchain nightly
+   make init
    ```
 
 3. Compile the Node Template
 
    ```bash
-   cd substrate-node-template/
-   cargo build --release
+   make build
    ```
 
 The time required for the compilation step depends on the hardware you're using. Don't wait before