diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 749d4f7..c22f0b1 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,6 +2,7 @@ - [Course Introduction]() - [Introduction](introduction.md) + - [Setup Instructions](instructions.md) - [Foundations of Rust]() - [Basic Syntax](basic-syntax.md) diff --git a/book/src/instructions.md b/book/src/instructions.md new file mode 100644 index 0000000..e929150 --- /dev/null +++ b/book/src/instructions.md @@ -0,0 +1,182 @@ +# Unit 1.2 - Introduction + +## Exercise 1.2.1: Setup Your Installation + +In this file you'll find instructions on how to install the tools we'll use during the course. + +All of these tools are available for Linux, macOS and Windows users. +We'll need the tools to write and compile our Rust code, and allow for remote mentoring. +*Important: these instructions are to be followed at home, before the start of the first tutorial.* +*If you have any problems with installation, contact the lecturers! We won't be addressing installation problems during the first tutorial.* + +## Rust and Cargo +First we'll need `rustc`, the standard Rust compiler. +`rustc` is generally not invoked directly, but through `cargo`, the Rust package manager. +`rustup` takes care of installing `rustc` and `cargo`. + +This part is easy: go to and follow the instructions. +Please make sure you're installing the latest default toolchain. +Once done, run + +```bash +rustc -V && cargo -V +``` + +The output should be something like this: + +```bash +rustc 1.79.0 (129f3b996 2024-06-10) +cargo 1.79.0 (ffa9cf99a 2024-06-03) +``` + +Using Rustup, you can install Rust toolchains and components. More info: +- +- + +## Rustfmt and Clippy +To avoid discussions, Rust provides its own formatting tool, Rustfmt. +We'll also be using Clippy, a collection of lints to analyze your code, that catches common mistakes for you. +You'll find that Rusts Clippy can be a very helpful companion. +Both Rustfmt and Clippy are installed by Rustup by default. + +To run Rustfmt on your project, execute: + +```bash +cargo fmt +``` + +To run clippy: + +```bash +cargo clippy +``` + +More info: +- Rustfmt: +- Clippy: + +## Visual Studio Code +During the course, we will use Visual Studio Code (vscode) to write code in. +Of course, you're free to use your favorite editor, but if you encounter problems, you can't rely on support from us. +Also, we'll use VSCode to allow for remote collaboration and mentoring during remote training sessions. + +You can find the installation instructions here: . + +We will install some plugins as well. +The first one is Rust-Analyzer. +Installation instructions can be found here . +Rust-Analyzer provides a lot of help during development and in indispensable when getting started with Rust. + +Another plugin we'll use is CodeLLDB. +This plugin enables debugging Rust code from within vscode. +You can find instructions here: . + +If you're following the training remotely, install the Live Share plugin as well. +We will use the plugin to share code and provide help during remote tutorial sessions. +Installation instructions can be found here: + +More info: +- +- + +## Git +During the trainings, you'll need the Git version control tool. +If you haven't installed Git already, you can find instructions here: . +If you're new to Git, you'll also appreciate GitHubs intro to Git and the Git intro with vscode, which you can find here: . + +More info: + +## Course code +Now that everything is installed, you can clone the source code repository using Git. +The repository can be found here: . + +Instructions on cloning the repository can be found here: + +### Trying it out +Now that you've got the code on your machine, navigate to it using your favorite terminal and run: + +``` +cd exercises/1-course-introduction/1-introduction/1-setup-your-installation +cargo run +``` + +This command may take a while to run the first time, as Cargo will first fetch the crate index from the registry. +It will compile and run the `intro` package, which you can find in `exercises/1-course-introduction/1-introduction/1-setup-your-installation`. +If everything goes well, you should see some output: + +``` + Compiling intro v0.1.0 ([/path/to/rust-workshop]/exercises/1-course-introduction/1-introduction/1-setup-your-installation) + Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.15s + Running `target/debug/intro` +🦀 Hello, world! 🦀 +You've successfully compiled and run your first Rust project! +X: 2; Y: 2 +``` +If Rust-Analyzer is set up correctly, you can also click the '▶️ Run'-button that is shown in `exercises/1-course-introduction/1-introduction/1-setup-your-installation/src/main.rs`. +With CodeLLDB installed correctly, you can also start a debug session by clicking 'Debug', right next to the '▶️ Run'-button. +Play a little with setting breakpoints by clicking on a line number, making a red circle appear and stepping over/into/out of functions using the controls. +You can view variable values by hovering over them while execution is paused, or by expanding the 'Local' view under 'Variables' in the left panel during a debug session. + +# Instructions for embedded +*This part is relevant only if you're partaking in one of the workshops on embedded Rust.* + +## Hardware +You should have a [BBC micro:bit](https://microbit.org/buy/bbc-microbit-single/ V2) available. + +You'll also need a Micro-USB cable, but we're sure you've got one to spare. + +Please check that everything is complete. If not, please contact us. + +## Software + +Then, we'll install some tools needed to flash the mcu and inspect the code. + +Install the `thumbv7em-none-eabihf` toolchain with the following command: +```bash +rustup target add thumbv7em-none-eabihf +``` + +We'll also install a couple of tools that let us inspect our binaries: + +```bash +rustup component add llvm-tools +cargo install cargo-binutils +``` + +Now, let's install [probe-rs](https://probe.rs). Follow the [installation instructions](https://probe.rs/docs/getting-started/installation/). Probe-rs talks with the debug interface on the micro:bit, to flash your application, log messages, or even set breakpoints and read out device memory. + +If you're on `linux`, you'll need to update your udev rules. +On ubuntu or fedora, run the following inside the workshop folder you just cloned; + +```bash +sudo cp 99-microbit-v2.rules /etc/udev/rules.d +sudo udevadm control --reload-rules +sudo udevadm trigger +``` + +If you're on `windows`, we need to install a generic WinUSB driver. You can use [Zadig](https://zadig.akeo.ie/) to select the usb device that uses the jlink driver and install WinUSB on it. +*This will uninstall the official driver, which means that the official Segger tools will not work anymore after this.* To revert, go to `device manager` and uninstall the usb device. The jlink driver will then be used again for that usb connection. + +Then, unplug the USB cable and plug it in again. + +## Trying it out +Before we begin, we need to test our hardware. We'll be testing the nRF52833 microcontroller and the LSM303AGR motion sensor, that are present on the micro:bit V2. Make sure you have checked out the latest version of the workshop source. + +### Running the test +To test the hardware, please connect the micro:bit V2 to your pc, switch it on, and run +```bash +cd ./exercises/1-course-introduction/1-introduction/2-embedded +cargo run --release +``` + +If everything works correctly, you should now see the accelerometer samples being printed on the display. If not, don't worry and contact us. + +## Docs +Datasheets, manuals, and schematics of the parts we are using in the embedded workshops. +### BBC micro:bit V2 +- [Hardware doc](https://tech.microbit.org/hardware/schematic/) +- [Schematic](https://github.com/microbit-foundation/microbit-v2-hardware/blob/main/V2.21/MicroBit_V2.2.1_nRF52820%20schematic.PDF) +### nRF52833 +- [nRF52833 product specification](https://infocenter.nordicsemi.com/pdf/nRF52833_PS_v1.6.pdf) +### LSM303AGR +- [Datsheet](https://www.st.com/resource/en/datasheet/lsm303agr.pdf) diff --git a/book/src/introduction.md b/book/src/introduction.md index 8cfafc4..f24c318 100644 --- a/book/src/introduction.md +++ b/book/src/introduction.md @@ -2,183 +2,23 @@ Slides -## Exercise 1.1.1: Setup Your Installation +On these pages you will find open source Rust training material designed and maintained by the Rust experts working at Tweede golf. +It comprises several modules that we use in our multi-day (embedded) training courses. -In this file you'll find instructions on how to install the tools we'll use during the course. +It is made available to you under the [CC-BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/), which means you +are free to use and share it as long as you give us appropriate credit and share any modifications you make +with others under that same license (which also means that we can use it to improve our training material!). -All of these tools are available for Linux, macOS and Windows users. -We'll need the tools to write and compile our Rust code, and allow for remote mentoring. -*Important: these instructions are to be followed at home, before the start of the first tutorial.* -*If you have any problems with installation, contact the lecturers! We won't be addressing installation problems during the first tutorial.* +The source for it can be found on our [GitHub repository](https://github.com/tweedegolf/rust-training). +If you see any mistake, we welcome issues and pull requests! -## Rust and Cargo -First we'll need `rustc`, the standard Rust compiler. -`rustc` is generally not invoked directly, but through `cargo`, the Rust package manager. -`rustup` takes care of installing `rustc` and `cargo`. +## Let us train you! -This part is easy: go to and follow the instructions. -Please make sure you're installing the latest default toolchain. -Once done, run +Going through this material on your own is good, but what's even better: our experts guiding your through the material and associated +exercise during an interactive, tailor-made multi-day program! -```bash -rustc -V && cargo -V -``` +To learn more, visit [our professional training page](https://tweedegolf.nl/en/expertise/rust/workshops). -The output should be something like this: +


-```bash -rustc 1.79.0 (129f3b996 2024-06-10) -cargo 1.79.0 (ffa9cf99a 2024-06-03) -``` - -Using Rustup, you can install Rust toolchains and components. More info: -- -- - -## Rustfmt and Clippy -To avoid discussions, Rust provides its own formatting tool, Rustfmt. -We'll also be using Clippy, a collection of lints to analyze your code, that catches common mistakes for you. -You'll find that Rusts Clippy can be a very helpful companion. -Both Rustfmt and Clippy are installed by Rustup by default. - -To run Rustfmt on your project, execute: - -```bash -cargo fmt -``` - -To run clippy: - -```bash -cargo clippy -``` - -More info: -- Rustfmt: -- Clippy: - -## Visual Studio Code -During the course, we will use Visual Studio Code (vscode) to write code in. -Of course, you're free to use your favorite editor, but if you encounter problems, you can't rely on support from us. -Also, we'll use VSCode to allow for remote collaboration and mentoring during remote training sessions. - -You can find the installation instructions here: . - -We will install some plugins as well. -The first one is Rust-Analyzer. -Installation instructions can be found here . -Rust-Analyzer provides a lot of help during development and in indispensable when getting started with Rust. - -Another plugin we'll use is CodeLLDB. -This plugin enables debugging Rust code from within vscode. -You can find instructions here: . - -If you're following the training remotely, install the Live Share plugin as well. -We will use the plugin to share code and provide help during remote tutorial sessions. -Installation instructions can be found here: - -More info: -- -- - -## Git -During the trainings, you'll need the Git version control tool. -If you haven't installed Git already, you can find instructions here: . -If you're new to Git, you'll also appreciate GitHubs intro to Git and the Git intro with vscode, which you can find here: . - -More info: - -## Course code -Now that everything is installed, you can clone the source code repository using Git. -The repository can be found here: . - -Instructions on cloning the repository can be found here: - -### Trying it out -Now that you've got the code on your machine, navigate to it using your favorite terminal and run: - -``` -cd exercises/1-course-introduction/1-introduction/1-setup-your-installation -cargo run -``` - -This command may take a while to run the first time, as Cargo will first fetch the crate index from the registry. -It will compile and run the `intro` package, which you can find in `exercises/1-course-introduction/1-introduction/1-setup-your-installation`. -If everything goes well, you should see some output: - -``` - Compiling intro v0.1.0 ([/path/to/rust-workshop]/exercises/1-course-introduction/1-introduction/1-setup-your-installation) - Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.15s - Running `target/debug/intro` -🦀 Hello, world! 🦀 -You've successfully compiled and run your first Rust project! -X: 2; Y: 2 -``` -If Rust-Analyzer is set up correctly, you can also click the '▶️ Run'-button that is shown in `exercises/1-course-introduction/1-introduction/1-setup-your-installation/src/main.rs`. -With CodeLLDB installed correctly, you can also start a debug session by clicking 'Debug', right next to the '▶️ Run'-button. -Play a little with setting breakpoints by clicking on a line number, making a red circle appear and stepping over/into/out of functions using the controls. -You can view variable values by hovering over them while execution is paused, or by expanding the 'Local' view under 'Variables' in the left panel during a debug session. - -# Instructions for embedded -*This part is relevant only if you're partaking in one of the workshops on embedded Rust.* - -## Hardware -You should have a [BBC micro:bit](https://microbit.org/buy/bbc-microbit-single/ V2) available. - -You'll also need a Micro-USB cable, but we're sure you've got one to spare. - -Please check that everything is complete. If not, please contact us. - -## Software - -Then, we'll install some tools needed to flash the mcu and inspect the code. - -Install the `thumbv7em-none-eabihf` toolchain with the following command: -```bash -rustup target add thumbv7em-none-eabihf -``` - -We'll also install a couple of tools that let us inspect our binaries: - -```bash -rustup component add llvm-tools -cargo install cargo-binutils -``` - -Now, let's install [probe-rs](https://probe.rs). Follow the [installation instructions](https://probe.rs/docs/getting-started/installation/). Probe-rs talks with the debug interface on the micro:bit, to flash your application, log messages, or even set breakpoints and read out device memory. - -If you're on `linux`, you'll need to update your udev rules. -On ubuntu or fedora, run the following inside the workshop folder you just cloned; - -```bash -sudo cp 99-microbit-v2.rules /etc/udev/rules.d -sudo udevadm control --reload-rules -sudo udevadm trigger -``` - -If you're on `windows`, we need to install a generic WinUSB driver. You can use [Zadig](https://zadig.akeo.ie/) to select the usb device that uses the jlink driver and install WinUSB on it. -*This will uninstall the official driver, which means that the official Segger tools will not work anymore after this.* To revert, go to `device manager` and uninstall the usb device. The jlink driver will then be used again for that usb connection. - -Then, unplug the USB cable and plug it in again. - -## Trying it out -Before we begin, we need to test our hardware. We'll be testing the nRF52833 microcontroller and the LSM303AGR motion sensor, that are present on the micro:bit V2. Make sure you have checked out the latest version of the workshop source. - -### Running the test -To test the hardware, please connect the micro:bit V2 to your pc, switch it on, and run -```bash -cd ./exercises/1-course-introduction/1-introduction/2-embedded -cargo run --release -``` - -If everything works correctly, you should now see the accelerometer samples being printed on the display. If not, don't worry and contact us. - -## Docs -Datasheets, manuals, and schematics of the parts we are using in the embedded workshops. -### BBC micro:bit V2 -- [Hardware doc](https://tech.microbit.org/hardware/schematic/) -- [Schematic](https://github.com/microbit-foundation/microbit-v2-hardware/blob/main/V2.21/MicroBit_V2.2.1_nRF52820%20schematic.PDF) -### nRF52833 -- [nRF52833 product specification](https://infocenter.nordicsemi.com/pdf/nRF52833_PS_v1.6.pdf) -### LSM303AGR -- [Datsheet](https://www.st.com/resource/en/datasheet/lsm303agr.pdf) +![Tweede golf logo](tweedegolf-logo.svg) diff --git a/book/src/tweedegolf-logo.svg b/book/src/tweedegolf-logo.svg new file mode 100644 index 0000000..3199616 --- /dev/null +++ b/book/src/tweedegolf-logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/slides/1_1-introduction.md b/slides/1_1-introduction.md index da7b50a..f7aa3e9 100644 --- a/slides/1_1-introduction.md +++ b/slides/1_1-introduction.md @@ -20,7 +20,7 @@ to build reliable and efficient software. --- -layout: two-cols +layout: trainer-intro --- # Who are we? @@ -29,17 +29,16 @@ layout: two-cols
- Embedded software engineer & Rust-lang trainer -- Joined Tweede golf in 2023 - Worked on ntpd-rs, statime, and [drive-rs](https://github.com/tweedegolf/drive-rs) -- Contributor to the Rust compiler - Worked in applied research in machine vision systems +- Taught the Embedded Rust Advanced class at EW24 ::right::

Photo Tamme
--- -layout: two-cols +layout: trainer-intro --- # Who are we? @@ -49,7 +48,6 @@ layout: two-cols
- Embedded tech lead & Rust-lang trainer -- Joined Tweede golf in 2021 - Full-time Rust since 2019 - Worked with LoRaWAN, UWB, LTE, PTP - Created sequential-storage, device-driver & nrf-modem crates @@ -61,7 +59,7 @@ layout: two-cols --- -layout: two-cols +layout: trainer-intro --- # Who are we? @@ -71,7 +69,6 @@ layout: two-cols
- Software engineer & Rust-lang trainer -- Joined Tweede golf in 2021 - Worked on NTP, PTP, P2000 - Contributor Roc programming language - Talk to me about compilers, linkers, functional & systems programming @@ -82,7 +79,7 @@ layout: two-cols --- -layout: two-cols +layout: trainer-intro --- # Who are we? @@ -92,9 +89,10 @@ layout: two-cols
- Software engineer & Rust-lang trainer -- Joined Tweede golf in 2022 - Worked on Sudo-rs, and ntpd-rs -- Taught and did CS research at Radboud University’s Security Group +- Formerly part of Radboud University’s Security Group +- Security officer worried about supply chain risks +- Talk to me about programming languages and formal verification ::right::
@@ -107,10 +105,11 @@ layout: with-footer # A quick note about Tweede golf -- **Leading Rust agency in NL** Running Rust in production since 2017 -- **Working on Rust adoption** Through both teach-rs and in-company trainings -- **Working on Rust projects** Like Rust implementations of PTP, NTP, sudo and su -- **Active community member** Organizing RustNL 2023 and active in various Rust meetups +- **Leading Rust experts** Running Rust in production since 2017 +- **Engineers** Web, systems, embedded software development +- **Open source** Impactful implementations of Network Time Protocol, sudo +- **Adoption** Through both teach-rs and in-company training +- **Community** Organizing RustNL and active in Rust meetups

@@ -166,14 +165,14 @@ layout: with-footer ```rust let t = thread::spawn(| | loop { -let question = Question::read_from_crowd(); -question.answer(); + let question = Question::read_from_crowd(); + question.answer(); }) for part in training.parts() { -part.slides(); -part.exercises(); + part.slides(); + part.exercises(); } t.join(); diff --git a/slides/layouts/trainer-intro.vue b/slides/layouts/trainer-intro.vue new file mode 100644 index 0000000..1acbb8e --- /dev/null +++ b/slides/layouts/trainer-intro.vue @@ -0,0 +1,42 @@ + + + + + diff --git a/slides/styles/code.css b/slides/styles/code.css index b6c3b47..986f1e9 100644 --- a/slides/styles/code.css +++ b/slides/styles/code.css @@ -10,11 +10,15 @@ p, li { display: none; } -div[layout="two-cols"] div.col-right { +div.two-columns div.col-right { padding-left: 10px; padding-top: 53px; } +div.trainer-intro div.col-left { + width: 150%; +} + img.logo { width: 175px; margin: 20px 10px;