From a3b4dcbefd4741f5481c5329c00869b08df15395 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Mon, 5 Nov 2018 02:01:52 +0100 Subject: [PATCH 1/5] remove link to the second edition of the Rust book its content is pretty similar to the 2018 edition and we want to reader to be familiar with the 2018 edition so it's best to direct them to that version of the Rust book --- src/intro/introduction.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/intro/introduction.md b/src/intro/introduction.md index b7dd754..f4d47c4 100644 --- a/src/intro/introduction.md +++ b/src/intro/introduction.md @@ -56,7 +56,6 @@ If you are unfamiliar with anything mentioned above or if you want more informat | Topic | Resource | Description | |--------------|----------|-------------| | Rust | [Rust Book 2018 Edition](https://doc.rust-lang.org/book/2018-edition/index.html) | If you are not yet comfortable with Rust, we highly suggest reading the this book. | -| Rust | [Rust Book Second Edition](https://doc.rust-lang.org/book/second-edition) | - | | Rust, Embedded | [Embedded Rust Bookshelf](https://docs.rust-embedded.org) | Here you can find several other resources provided by Rust's Embedded Working Group. | | Rust, Embedded | [Embedonomicon](https://docs.rust-embedded.org/embedonomicon/) | The nitty gritty details when doing embedded programming in Rust. | | Rust, Embedded | [embedded FAQ](https://docs.rust-embedded.org/faq.html) | Frequently asked questions about Rust in an embedded context. | From d6ab8b0f657c727dc57158df8a8dc5f5eb13352c Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Mon, 5 Nov 2018 02:03:13 +0100 Subject: [PATCH 2/5] s/version/section --- src/intro/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/intro/introduction.md b/src/intro/introduction.md index f4d47c4..f7055d7 100644 --- a/src/intro/introduction.md +++ b/src/intro/introduction.md @@ -85,7 +85,7 @@ for the purpose of following the examples in this book. > **HEADS UP** Until the official release of this book, which is planned to > coincide with the 2018 edition release of the Rust Programming Language, > expect the sections of this book to change quite a bit. We recommend -> bookmarking the root of this book instead of any specific version. +> bookmarking the root of this book instead of any specific section. ## Contributing to This Book From 6ad3574b4389c80a359780d57844ee53ec156eb8 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Mon, 5 Nov 2018 02:06:06 +0100 Subject: [PATCH 3/5] recommend 1.31-beta --- src/intro/install.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/src/intro/install.md b/src/intro/install.md index 80f0fa7..d4631c2 100644 --- a/src/intro/install.md +++ b/src/intro/install.md @@ -2,8 +2,6 @@ > > Contents should be updated to work on `stable` Rust when possible -> **⚠️: This section was last checked on 2018-09-13** - # Setting up a Development Environment Dealing with microcontrollers involves using several different tools as we'll be @@ -40,8 +38,8 @@ and debug programs on a *remote* device. We'll use all the tools listed below. Any recent version should work when a minimum version is not specified, but we have listed the versions we have tested. -- Rust 1.30, 1.30-beta, nightly-2018-09-13, or a newer toolchain PLUS ARM - Cortex-M compilation support. +- Rust 1.31, 1.31-beta, or a newer toolchain PLUS ARM Cortex-M compilation + support. - [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils) ~0.1.4 - [`qemu-system-arm`](https://www.qemu.org/). Tested versions: 3.0.0 - OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0 @@ -63,13 +61,12 @@ Then switch to the beta channel. $ rustup default beta ``` -**NOTE** Make sure you have a beta equal to or newer than `1.30-beta`. `rustc --V` should return a date newer than the one shown below. If `1.30-beta` is not -out yet then use the nightly channel for the time being. +**NOTE** Make sure you have a beta equal to or newer than `1.31-beta`. `rustc +-V` should return a date newer than the one shown below. ``` console $ rustc -V -rustc 1.30.0-beta (????????? 2018-09-1?) +rustc 1.31.0-beta.4 (04da282bb 2018-11-01) ``` For bandwidth and disk usage concerns the default installation only supports From 15c4b8f60b924db32069ff49322dfc106d719b79 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Mon, 5 Nov 2018 02:19:13 +0100 Subject: [PATCH 4/5] remove warnings --- src/intro/install.md | 4 ---- src/intro/install/linux.md | 2 -- src/intro/install/macos.md | 2 -- src/intro/install/windows.md | 2 -- 4 files changed, 10 deletions(-) diff --git a/src/intro/install.md b/src/intro/install.md index d4631c2..dcd20a9 100644 --- a/src/intro/install.md +++ b/src/intro/install.md @@ -1,7 +1,3 @@ -> **⚠️: This section still references `beta` Rust** -> -> Contents should be updated to work on `stable` Rust when possible - # Setting up a Development Environment Dealing with microcontrollers involves using several different tools as we'll be diff --git a/src/intro/install/linux.md b/src/intro/install/linux.md index 5f598e3..30ad63e 100644 --- a/src/intro/install/linux.md +++ b/src/intro/install/linux.md @@ -1,5 +1,3 @@ -> **⚠️: This section was last checked on 2018-09-13 - # Linux Here are the installation commands for a few Linux distributions. diff --git a/src/intro/install/macos.md b/src/intro/install/macos.md index 450b284..6caa487 100644 --- a/src/intro/install/macos.md +++ b/src/intro/install/macos.md @@ -1,5 +1,3 @@ -> **⚠️: This section has not been checked as of 2018-09-13** - # macOS All the tools can be install using [Homebrew]: diff --git a/src/intro/install/windows.md b/src/intro/install/windows.md index 4f202b7..fc19ead 100644 --- a/src/intro/install/windows.md +++ b/src/intro/install/windows.md @@ -1,5 +1,3 @@ -> **⚠️: This section has not been checked as of 2018-09-13** - # Windows ## `arm-none-eabi-gdb` From 9da22bdd21750bb5ab7cb8b92c36487fb1b40837 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Tue, 6 Nov 2018 19:39:11 +0100 Subject: [PATCH 5/5] move sections around explain the tools before showing the installation steps cover no_std before the tooling --- src/SUMMARY.md | 4 ++-- src/intro/install.md | 49 ++------------------------------------------ src/intro/tooling.md | 29 +++++++++++++++++++++----- 3 files changed, 28 insertions(+), 54 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index db6fce2..36025bc 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -10,14 +10,14 @@ more information and coordination --> - [Introduction](./intro/introduction.md) + - [`no_std`](./intro/no-std.md) + - [Tooling](./intro/tooling.md) - [Installation](./intro/install.md) - [Linux](./intro/install/linux.md) - [MacOS](./intro/install/macos.md) - [Windows](./intro/install/windows.md) - [Verify Installation](./intro/install/verify.md) - - [Tooling](./intro/tooling.md) - [Hardware](./intro/hardware.md) - - [`no_std`](./intro/no-std.md) - [Getting started](./start.md) - [QEMU](./start/qemu.md) - [Hardware](./start/hardware.md) diff --git a/src/intro/install.md b/src/intro/install.md index dcd20a9..4abd819 100644 --- a/src/intro/install.md +++ b/src/intro/install.md @@ -1,51 +1,6 @@ -# Setting up a Development Environment +# Installing the tools -Dealing with microcontrollers involves using several different tools as we'll be -dealing with an architecture different than your laptop's and we'll have to run -and debug programs on a *remote* device. - - - - - - - - - - - - - - - - - - - - - - - - - - - -## Tools - -We'll use all the tools listed below. Any recent version should work when a minimum version is not specified, but we have listed the versions we have tested. - -- Rust 1.31, 1.31-beta, or a newer toolchain PLUS ARM Cortex-M compilation - support. -- [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils) ~0.1.4 -- [`qemu-system-arm`](https://www.qemu.org/). Tested versions: 3.0.0 -- OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0 -- GDB with ARM support. Version 7.12 or newer highly recommended. Tested - versions: 7.10, 7.11, 7.12 and 8.1 -- [OPTIONAL] `git` OR - [`cargo-generate`](https://github.com/ashleygwilliams/cargo-generate). If you - have neither installed then don't worry about installing either. - -Next, follow OS-agnostic installation instructions for a few of the tools: +This page contains OS-agnostic installation instructions for a few of the tools: ### Rust Toolchain diff --git a/src/intro/tooling.md b/src/intro/tooling.md index feecf91..d12813d 100644 --- a/src/intro/tooling.md +++ b/src/intro/tooling.md @@ -1,6 +1,26 @@ # Tooling -This section contains details about the tools we'll be using. +Dealing with microcontrollers involves using several different tools as we'll be +dealing with an architecture different than your laptop's and we'll have to run +and debug programs on a *remote* device. + +We'll use all the tools listed below. Any recent version should work when a +minimum version is not specified, but we have listed the versions we have +tested. + +- Rust 1.31, 1.31-beta, or a newer toolchain PLUS ARM Cortex-M compilation + support. +- [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils) ~0.1.4 +- [`qemu-system-arm`](https://www.qemu.org/). Tested versions: 3.0.0 +- OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0 +- GDB with ARM support. Version 7.12 or newer highly recommended. Tested + versions: 7.10, 7.11, 7.12 and 8.1 +- [OPTIONAL] `git` OR + [`cargo-generate`](https://github.com/ashleygwilliams/cargo-generate). If you + have neither installed then don't worry about installing either. + +The text below explains why we are using these tools. Installation instructions +can be found in the next page. ## `cargo-generate` OR `git` @@ -36,9 +56,9 @@ can follow some parts of this book even if you don't have any hardware with you! ## GDB -Debugging is very important skill for embedded development as you may not always -have the luxury to log stuff to the host console. In some cases, you may not -have LEDs to blink on your hardware! +A debugger is a very important component of embedded development as you may not +always have the luxury to log stuff to the host console. In some cases, you may +not have LEDs to blink on your hardware! In general, LLDB works as well as GDB when it comes to debugging but we haven't found an LLDB counterpart to GDB's `load` command, which uploads the program to @@ -63,4 +83,3 @@ development board: * Continuing CPU execution after a debug event has been encountered * etc. * It also knows how to erase and write to the microcontroller's FLASH -