diff --git a/docs/rust-setup.md b/docs/rust-setup.md index ea133ca..6cd606d 100644 --- a/docs/rust-setup.md +++ b/docs/rust-setup.md @@ -2,9 +2,6 @@ title: Installation --- -This guide is for reference only, please check the latest information on getting starting with Substrate -[here](https://docs.substrate.io/v3/getting-started/installation/). - This page will guide you through the **2 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 @@ -12,11 +9,11 @@ on the computer's operating system. Once Rust is configured, you will use its to with Rust projects; the commands for Rust's toolchains will be the same for all supported, Unix-based operating systems. -## Build dependencies +## 1. Build dependencies Substrate development is easiest on Unix-based operating systems like macOS or Linux. The examples -in the [Substrate Docs](https://docs.substrate.io) use Unix-style terminals to demonstrate how to -interact with Substrate from the command line. +in the Substrate [Tutorials](/tutorials) and [How-to Guides](/how-to-guides) +use Unix-style terminals to demonstrate how to interact with Substrate from the command line. ### Ubuntu/Debian @@ -25,7 +22,7 @@ Use a terminal shell to execute the following commands: ```bash sudo apt update # May prompt for location information -sudo apt install -y git clang curl libssl-dev llvm libudev-dev +sudo apt install -y git clang curl libssl-dev llvm libudev-dev pkg-config make ``` ### Arch Linux @@ -33,7 +30,7 @@ sudo apt install -y git clang curl libssl-dev llvm libudev-dev Run these commands from a terminal: ```bash -pacman -Syu --needed --noconfirm curl git clang +pacman -Syu --needed --noconfirm curl git clang make ``` ### Fedora @@ -42,7 +39,7 @@ Run these commands from a terminal: ```bash sudo dnf update -sudo dnf install clang curl git openssl-devel +sudo dnf install clang curl git openssl-devel make ``` ### OpenSUSE @@ -50,15 +47,12 @@ sudo dnf install clang curl git openssl-devel Run these commands from a terminal: ```bash -sudo zypper install clang curl git openssl-devel llvm-devel libudev-devel +sudo zypper install clang curl git openssl-devel llvm-devel libudev-devel make ``` ### macOS -> **Apple M1 ARM** -> If you have an Apple M1 ARM system on a chip, make sure that you have Apple Rosetta 2 -> installed through `softwareupdate --install-rosetta`. This is only needed to run the -> `protoc` tool during the build. The build itself and the target binaries would remain native. +> If you have an Apple M1 ARM system on a chip, make sure that you have Apple Rosetta 2 installed through \`softwareupdate --install-rosetta\`. This is only needed to run the \`protoc\` tool during the build. The build itself and the target binaries would remain native." Open the Terminal application and execute the following commands: @@ -73,13 +67,12 @@ brew install openssl ### Windows -**_PLEASE NOTE:_** Native development of Substrate is _not_ very well supported! It is _highly_ -recommend to use [Windows Subsystem Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) -(WSL) and follow the instructions for [Ubuntu/Debian](#ubuntudebian). -Please refer to the separate -[guide for native Windows development](https://docs.substrate.io/v3/getting-started/windows-users/). +> Native development of Substrate is _not_ very well supported! +> It is _highly_ recommend to +use [Windows Subsystem Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) (WSL) +and follow the instructions for [Ubuntu/Debian](#ubuntudebian). -## Rust developer environment +## 2. Rust developer environment This guide uses installer and the `rustup` tool to manage the Rust toolchain. First install and configure `rustup`: @@ -103,11 +96,13 @@ rustup target add wasm32-unknown-unknown --toolchain nightly ## Test your set-up Now the best way to ensure that you have successfully prepared a computer for Substrate -development is to follow the steps in [our first Substrate tutorial](https://docs.substrate.io/tutorials/v3/create-your-first-substrate-chain/). +development is to follow the steps in [our first tutorial](https://docs.substrate.io/tutorials/v3/create-your-first-substrate-chain/). + +> For more details on _why_ these dependencies are used, and for _troubleshooting_ errors building the template, read on. ## Troubleshooting Substrate builds -Sometimes you can't get the Substrate node template +Sometimes you can't get the [Substrate node template](https://github.com/substrate-developer-hub/substrate-node-template) to compile out of the box. Here are some tips to help you work through that. ### Rust configuration check @@ -156,8 +151,10 @@ 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 runtime code to the Wasm target. -> There are upstream issues in Rust that need to be resolved before all of Substrate can use the stable Rust toolchain. -> [This is our tracking issue](https://github.com/paritytech/substrate/issues/1252) if you're curious as to why and how this will be resolved. +> There are upstream issues in Rust that need to be resolved before all of Substrate can use +the stable Rust toolchain. +> [This is our tracking issue](https://github.com/paritytech/substrate/issues/1252) +if you're curious as to why and how this will be resolved. #### Latest nightly for Substrate `master` @@ -172,12 +169,17 @@ rustup update nightly rustup target add wasm32-unknown-unknown --toolchain nightly ``` -> NOTE: 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. When you do this, both your nightly -> and stable toolchains will be pulled to the most recent release, and for nightly, it is -> generally _not_ expected to compile WASM without error (although it very often does). -> Be sure to [specify your nightly version](#specifying-nightly-version) if you get WASM build errors -> from `rustup` and [downgrade nightly as needed](#downgrading-rust-nightly). +
+ #### Rust nightly toolchain @@ -210,15 +212,16 @@ project should use for Wasm compilation: WASM_BUILD_TOOLCHAIN=nightly- cargo build --release ``` -> Note that this only builds _the runtime_ with the specified nightly. The rest of project will be -> compiled with **your default toolchain**, i.e. the latest installed stable toolchain. +> Note that this only builds _the runtime_ with the specified nightly. +> The rest of project will be compiled with **your default toolchain**, i.e. the latest installed stable toolchain. + ### 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: -```bash +```sh rustup uninstall nightly rustup install nightly- rustup target add wasm32-unknown-unknown --toolchain nightly-