diff --git a/src/SUMMARY.md b/src/SUMMARY.md index b5247a65315d27fb664b46b5b8ce34ed4b38f02f..87525677670ad1b4cfc0d5bd4d9a9d502bcccd41 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,6 +4,9 @@ - [Introduction to the hardware](./ch1_01_hardware.md) - [Introduction to the software](./ch1_02_software.md) - [Installation of toolchain](./ch2_00_installation.md) + - [Linux Toolchain setup](./ch2_01_linux_installation.md) + - [Windows Toolchain setup](./ch2_02_windows_installation.md) + - [Testing the toolchain](./ch2_03_testing_toolchain.md) - [Exercises - learning by doing](./ch3_00_exercises.md) - [Getting started with the hardware](./ch3_01_getting_started.md) - [Blinking a LED](./ch3_02_blinky.md) diff --git a/src/ch2_00_installation.md b/src/ch2_00_installation.md index 386bb75fbf8e07fd3965eb62c85eb7188a1a3699..918894b9f36a92fd211f98da669c99efa5f15200 100644 --- a/src/ch2_00_installation.md +++ b/src/ch2_00_installation.md @@ -1,141 +1,22 @@ # Installation of toolchain -## Rust - -Go to [https://rustup.rs/](https://rustup.rs/) and follow the instructions. - -### Cargo tools -``` -cargo install cargo-binutils -rustup component add llvm-tools-preview -``` +Pick the appropriate subchapter for your operating system. ## Editor -There is no requirement on what editor you should use, but if you are undecided VS code offers quite a few features, is free and highly customizable. It also features quite a lot of extensions, for an example, the Rust core group maintain an extension that is called ```Rust (rls)``` where you get all kinds of language-specific help such as code completion, IntelliSense, refactoring, reformatting, errors, snippets. +There is no requirement on which editor you should use, +but if you are undecided VS code offers quite a few nice features, +is free and highly customizable. + +It is also modular with a lot of extensions, including for example, the Rust core group maintained extension that is called ```Rust (rls)``` where you get all kinds of language-specific help such as code completion, IntelliSense, refactoring, reformatting, errors, snippets. ### VS Code -* Windows: Go to https://code.visualstudio.com/docs/setup/windows and follow the instructions +* Windows: Go to [VS Code for Windows](https://code.visualstudio.com/docs/setup/windows) and follow the instructions -* Linux: Use package manager of choice, see: https://code.visualstudio.com/docs/setup/linux +* Linux: Use package manager of choice, see: [VS Code for Linux](https://code.visualstudio.com/docs/setup/linux) #### VS Code plugins When installed, go to the extensions tab and install ```Rust (rls)``` and ```Better TOML```. +[Rust Analyzer](https://github.com/rust-analyzer/rust-analyzer) is an alternative to ```Rust (rls)``` -## Linux - -In general use your package manager for whatever distribution you are using. - -Some LTS distributions may have very old packages, but it should work, -in case of troubles see if the package is available in the `backports` repositories. - -### GDB / Binutils - -Debian - -``` -sudo apt install gdb-arm-none-eabi binutils-arm-none-eabi -``` - -Ubuntu - -``` -sudo apt install gcc-multilibA gdb-multiarch binutils-multiarch -``` - - -Arch - -``` -sudo pacman -S arm-none-eabi-gdb arm-none-eabi-binutils -``` - -### OpenOCD - -Debian/Ubuntu - -``` -sudo apt install openocd -``` - -Arch - -``` -sudo pacman -S openocd -``` - - -## Windows - -### Native - -#### GDB - -Go to http://www.mingw.org/, download and install MinGW. In the MinGW Installation Manager select ```All Packages``` then mark for installation: -- mingw32-gcc-g++ -- mingw32-gdb (bin) -- mingw32-gdb (doc) -- mingw32-gdb (info) -- mingw32-gdb (lic) -- mingw32-gdb (man) - -then in the Installation menu choose ```Apply Changes```, you should see at the bottom of the window that there is going to be several packages in ```new/upgraded packages will be installed``` if so then click ```Apply```. - -If everything went as expected then you should have the ```gdb.exe``` file is your MinGW install folder under /bin. However to effectively use gdb you need to set the environment variable. -Go to the Control panel -> System and Security -> System -> Advanced system settings, click the ```Environment Variables...``` button. In this window in the System variables view click ```Edit...``` then ```New``` and type in the path to the gdb.exe file (should be something like ```C:\MinGW\bin```). Then click OK in all the windows. - -To check that everything went as expected open a new terminal with ```CTRL+r``` and type cmd then ```ENTER```. -If you now type ```gdb`` you should be prompted with a text saying something like "GNU gdb (GDB) 7.6.1", gdb is now installed! - -#### OpenOCD - -Go to http://gnutoolchains.com/arm-eabi/openocd/ and download the latest OpenOCD package. -Extract the package somewhere where it is easy to find (i.e C:). - - -/// TODO /// - -### Windows Subsystem for Linux (WSL) - Windows 10 ONLY - -To install WSL check out: https://docs.microsoft.com/en-us/windows/wsl/install-win10. We recommend the Ubuntu distro. - -To open a distro terminal: Ctrl+r and write ```cmd``` and run. In the terminal type ```bash```, this will spawn a ubuntu terminal. - -Using the terminal, update the distro: - -```sudo apt update``` - -```sudo apt install build-essential``` - -```sudo apt install gdb``` - -```sudo apt upgrade``` - -The ordinary C: drive will be found under /mnt/c - -#### Rust - -Continue in the terminal and write: - -```curl https://sh.rustup.rs -sSf | sh``` - -#### GDB - -/// TODO /// - -#### OpenOCD - -Is the same as for native Windows as OpenOCD doesn't (currently) work under WSL. - -#### Quality of life - -##### Shortcuts - -To be able to quickly get up and running I usually create a shortcut on the desktop with all flags I need for a certain project and with the configurations that I need. For example, if I have a project that uses OpenOCD, the STLink programmer and the target MCU is an STM32f4xx, I create a shortcut with the target: - -```C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe .\openocd.exe -f ../share/openocd/scripts/interface/stlink.cfg -f ../share/openocd/scripts/target/stm32f4x.cfg``` - -and make it start in the openocd/bin folder i.e ```C:\OpenOCD\bin```. And if you want to be really fancy then under layout you can change where the window should spawn as well as how it should look like. - -You can even make it spawn a WSL terminal to your liking, for example, if you have the target set as ```C:\Windows\System32\bash.exe -c "tmux new-session \; split-window -h \; attach"``` and to start in the folder where your rust projects are located. Then you will have a bash terminal in your project folder under WSL that starts up with tmux creating two panes splitting the terminal in two. diff --git a/src/ch2_01_linux_installation.md b/src/ch2_01_linux_installation.md new file mode 100644 index 0000000000000000000000000000000000000000..9d31013824e428f26c75b39161d48f32ad9fad75 --- /dev/null +++ b/src/ch2_01_linux_installation.md @@ -0,0 +1,52 @@ +# Linux Toolchain setup + +In general use your package manager for whatever distribution you are using. + +Some Long-Term-Support distributions may have very old packages, but it should work, +in case of troubles see if the package is available in the `backports` repositories. + +## GDB / Binutils + +Debian + +``` +sudo apt install gdb-arm-none-eabi binutils-arm-none-eabi +``` + +Ubuntu + +``` +sudo apt install gcc-multilib gdb-multiarch binutils-multiarch +``` + + +Arch + +``` +sudo pacman -S arm-none-eabi-gdb arm-none-eabi-binutils +``` + +## OpenOCD + +Debian/Ubuntu + +``` +sudo apt install openocd +``` + +Arch + +``` +sudo pacman -S openocd +``` + +## Rust + +Go to [https://rustup.rs/](https://rustup.rs/) and follow the instructions. + + +## Cargo tools +``` +cargo install cargo-binutils +rustup component add llvm-tools +``` diff --git a/src/ch2_02_windows_installation.md b/src/ch2_02_windows_installation.md new file mode 100644 index 0000000000000000000000000000000000000000..2806815875208da183182894a4f0d2c7288f215d --- /dev/null +++ b/src/ch2_02_windows_installation.md @@ -0,0 +1,77 @@ +# Windows Toolchain setup + +### Native + +#### GDB + +Go to [mingw.org](http://www.mingw.org/), download and install MinGW. In the MinGW Installation Manager select ```All Packages``` then mark for installation: +- mingw32-gcc-g++ +- mingw32-gdb (bin) +- mingw32-gdb (doc) +- mingw32-gdb (info) +- mingw32-gdb (lic) +- mingw32-gdb (man) + +then in the Installation menu choose ```Apply Changes```, you should see at the bottom of the window that there is going to be several packages in ```new/upgraded packages will be installed``` if so then click ```Apply```. + +If everything went as expected then you should have the ```gdb.exe``` file is your MinGW install folder under /bin. However to effectively use gdb you need to set the environment variable. +Go to the Control panel -> System and Security -> System -> Advanced system settings, click the ```Environment Variables...``` button. In this window in the System variables view click ```Edit...``` then ```New``` and type in the path to the gdb.exe file (should be something like ```C:\MinGW\bin```). Then click OK in all the windows. + +To check that everything went as expected open a new terminal with ```CTRL+r``` and type cmd then ```ENTER```. +If you now type ```gdb``` you should be prompted with a text saying something like "GNU gdb (GDB) 7.6.1", gdb is now installed! + +#### OpenOCD + +Go to [openocd](http://gnutoolchains.com/arm-eabi/openocd/) and download the latest OpenOCD package. +Extract the package somewhere where it is easy to find (i.e C:). + + +/// TODO /// + +### Windows Subsystem for Linux (WSL) - Windows 10 ONLY + +To install WSL check out: [https://docs.microsoft.com/en-us/windows/wsl/install-win10](https://docs.microsoft.com/en-us/windows/wsl/install-win10). We recommend the Ubuntu distro. + +To open a distro terminal: Ctrl+r and write ```cmd``` and run. In the terminal type ```bash```, this will spawn a ubuntu terminal. + +Using the terminal, update the distro: + +```sudo apt update``` + +```sudo apt install build-essential``` + +```sudo apt install gdb``` + +```sudo apt upgrade``` + +The ordinary C: drive will be found under /mnt/c + +#### Rust + +Go to [https://rustup.rs/](https://rustup.rs/) and follow the instructions, run the command inside WSL. + +##### Cargo tools +``` +cargo install cargo-binutils +rustup component add llvm-tools +``` + +#### GDB + +/// TODO /// + +#### OpenOCD + +Is the same as for native Windows as OpenOCD doesn't (currently) work under WSL. + +#### Quality of life + +##### Shortcuts + +To be able to quickly get up and running I usually create a shortcut on the desktop with all flags I need for a certain project and with the configurations that I need. For example, if I have a project that uses OpenOCD, the STLink programmer and the target MCU is an STM32f4xx, I create a shortcut with the target: + +```C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe .\openocd.exe -f ../share/openocd/scripts/interface/stlink.cfg -f ../share/openocd/scripts/target/stm32f4x.cfg``` + +and make it start in the openocd/bin folder i.e ```C:\OpenOCD\bin```. And if you want to be really fancy then under layout you can change where the window should spawn as well as how it should look like. + +You can even make it spawn a WSL terminal to your liking, for example, if you have the target set as ```C:\Windows\System32\bash.exe -c "tmux new-session \; split-window -h \; attach"``` and to start in the folder where your rust projects are located. Then you will have a bash terminal in your project folder under WSL that starts up with tmux creating two panes splitting the terminal in two. diff --git a/src/ch2_03_testing_toolchain.md b/src/ch2_03_testing_toolchain.md new file mode 100644 index 0000000000000000000000000000000000000000..c1420b7d3c4e9682ec3674e50bbe0a6428c358f9 --- /dev/null +++ b/src/ch2_03_testing_toolchain.md @@ -0,0 +1 @@ +# Testing the toolchain