diff --git a/src/README.md b/src/README.md index c59c223..6414fca 100644 --- a/src/README.md +++ b/src/README.md @@ -16,17 +16,3 @@ This guide will introduce you to NEAR, Rust, and RAEN. ### About the name "RAEN" is "NEAR" spelled backwards. It is pronounced the same as "rain". - -# Getting Set Up - -[Install RAEN](https://github.com/raendev/raen), then clone the examples repository to follow along: - -```bash -git clone --depth 1 --branch v0.0.3 https://github.com/raendev/examples.git --recursive -``` - - diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c990272..7cf7ae4 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,7 +1,8 @@ # Summary -[Introduction](README.md) - +- [Introduction](README.md) + - [Who is this for?](./intro/who-is-this-for.md) + - [Getting Set Up](./intro/getting-set-up.md) - [Counter](./counter/intro.md) - [Defining the data](counter/first_steps.md) - [Implementation](counter/impl.md) diff --git a/src/intro/getting-set-up.md b/src/intro/getting-set-up.md new file mode 100644 index 0000000..575c148 --- /dev/null +++ b/src/intro/getting-set-up.md @@ -0,0 +1,68 @@ +# Getting Set Up + +1. Install or update Rust: + + ```bash + curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh + ``` + + See [full instructions in the Rust Book](https://doc.rust-lang.org/book/ch01-01-installation.html). + +2. Add the [WebAssembly](https://webassembly.org/) (Wasm) toolchain: + + ```bash + rustup target add wasm32-unknown-unknown + ``` + + NEAR smart contracts need to be compiled to 32-bit Wasm with _architecture_ and _platform_ both "unknown". + + +3. Install RAEN: + + ```bash + cargo install raen + ``` + + This will install `raen` globally, so it doesn't matter where you run it. + + `cargo` was installed with Rust. Cargo is [the Rust package manager](https://doc.rust-lang.org/cargo/index.html), like NPM for NodeJS. Rust packages are called _crates_. `raen` is a Rust crate. + +4. Install `near-cli`: + + Prerequisite: [install NodeJS](https://nodejs.dev/learn/how-to-install-nodejs). + + ```bash + npm install --global near-cli + ``` + + There is a Rust version of near-cli [in the works](https://github.com/near/near-cli-rs), but it's not ready yet. Someday `raen` will wrap `near` (or work with the new Rust-based CLI as a plugin), allowing you to only install one package. But for now, you need both. + +5. Configure your editor. + + In Visual Studio Code, install the [rust-analyzer extension](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer). + + The tools [recommended by the Rust Book](https://doc.rust-lang.org/book/appendix-04-useful-development-tools.html) will give you further superpowers, making you feel comfy and productive in no time. + +6. Clone the Examples repository: + + ```bash + git clone --depth 1 --branch v0.0.3 https://github.com/raendev/examples.git --recursive raen-examples + ``` + + This will clone [github.com/raendev/examples](https://github.com/raendev/examples) to a folder called `raen-examples`. + +7. Build with RAEN. + + Change into `raen-examples/contracts/rust-counter`, then build: + + ```bash + raen build --release + ``` + + This may take a minute. Rust fetches dependencies and compiles your project in one step. It will go faster on subsequent runs. + + If you skip this, the editor setup from Step 5 won't work. + +8. Open an example. + + We're going to start with `raen-examples/contracts/rust-counter`. Open this folder in your editor. Let's take a look around. diff --git a/src/intro/who-is-this-for.md b/src/intro/who-is-this-for.md new file mode 100644 index 0000000..1dde493 --- /dev/null +++ b/src/intro/who-is-this-for.md @@ -0,0 +1,25 @@ +# Who is this for? + +App developers. + +If you're wondering what a blockchain even is or what effects it might have on the world, you can find lots of other introductions. Here's a [booster](https://martinhiesboeck.blog/2018/04/02/how-blockchain-will-save-the-world/), a [doomer](https://www.youtube.com/watch?v=YQ_xWvX1n9g), [some](https://www.youtube.com/watch?v=YQ_xWvX1n9g) [discussions](https://www.nytimes.com/2022/04/05/opinion/ezra-klein-podcast-dan-olson.html), and a [refreshingly neutral intro](https://www.nytimes.com/interactive/2022/03/18/technology/cryptocurrency-crypto-guide.html). + +If you want to know how blockchains work, there's lots of other introductions for that, too. You can learn about [Proof of Work](https://www.3blue1brown.com/lessons/bitcoin) and [Proof of Stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/) and read [lots](https://bitcoinwhitepaper.co/) [of](https://ethereum.org/en/whitepaper/) [whitepapers](https://docs.near.org/docs/concepts/architecture/papers). + +This guide sits in between such philosophical intros and nitty-gritty explainers. + +If you want to learn how to actually _use_ a blockchain, this guide is for you. You'll get a gentle introduction to Rust, the [most-loved language for seven years running](https://insights.stackoverflow.com/survey/2021#technology-most-loved-dreaded-and-wanted), and a gentle introduction to NEAR. + +This guide assumes you have experience with the command line and at least one programming language. That's it. + +If you're already experienced with some other blockchain, you'll be able to go a bit faster through some parts. + +If you already have experience with Rust, you can probably skip certain parts and just look for the NEAR-specific stuff. + +If you're already experienced with Rust and NEAR, you probably don't need to stick around. Just go use RAEN. Have a great time! + +