@@ -7,17 +7,18 @@ The `rustc` compiler is at heart of the Rust Ecosystem. Other tools of great hel
*[cargo-update](https://crates.io/crates/cargo-update), cargo sub-command to manage crate updates
*[xargo](https://crates.io/crates/xargo) Systoot manager to build for non-`std` targets
Various other Rust tools you might find useful
*[rls](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust), Rust support for Visual Studio Code
The Rust ecosystem also provides support to program development, in terms of external `crates` for code completion formatting and formatting
*[racer](https://crates.io/crates/racer/), Code completion for Rustbuild system and package/crate manager
*[rustfmt](https://crates.io/crates/rustfmt), Tool to find and fix Rust formatting issues
*[itm](https://crates.io/crates/itm) Tool to parse and dump ITM packets
* add here your favorite crates
*[rls-preview](https://github.com/rust-lang-nursery/rls), Rust Language Server (RLS). RLS is a server that runs in the background, providing IDEs, editors, and other tools with information about Rust programs. The `rls-preview` is in alpha state, meaning that its not guaranteed to compile/work. (You may check under build/passing, the latest changes that passed compilation.)
Rust support for various IDEs and editors
*[rls](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust), Rust support for Visual Studio Code, based on the `rls-preview`. This is the refererence implementation for `rls` support (currently in alpha/preview state).
*[rustdt](http://rustdt.github.io/), Rust support for the Eclipse platform (currently not further maintained)
* Atom, Sublime, Code::Blocks support is also available
Other tools and packages
*[rls](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust), Rust support for Visual Studio Code
*[rustdt](http://rustdt.github.io/), Rust support for the Eclipse platform
Other tools that come in handy for embedded development
*[itm](https://crates.io/crates/itm) Tool to parse and dump ITM packets
* add here your favorite tools supproting Rust development
# Installation
...
...
@@ -26,12 +27,64 @@ We suggest a linux or OSX development environment, though Rust related tools are
# Rustup
The [rustup](https://www.rustup.rs/), tool manager allows you to manage multiple tool chain installations. Nightly tool chains allow for the development of libraries and applations including `unsafe` code (which will be necessary for the later excercises). For some tools to work (rls/rustfmt) you need to install the Rust sources. By default your Rust related tools will be stored in `~/.rustup`.
The [rustup](https://www.rustup.rs/), tool manager allows you to manage multiple tool chain installations. Rust is distrubuted in three channels (`stable`, `beta` and `nightly`). You may set the default toolchain:
Nightly tool chains allow for the development of libraries and applations including `unsafe` code using features not available on the `stable channel` (which will be necessary for the later excercises). For some tools to work (`rls/rustfmt`) you need to install additional components. For this to work, you should use a nightly toolchain for which all tools and components work (currently `nightly-2017-10-22-x86_64-unknown-linux-gnu` is the latest). Here is an example:
`rls-preview`, `rust-analysis` and `rust-src` are required for RLS support (including cross referencing to the standard library, code completion and formatting).
# Cargo
Cargo is the go-to tool for managing Rust application and your own Rust developments (see [cargo](https://crates.io/) for for detailed documentation).
By default your Rust related tools will be stored in `~/.cargo`, this directory should be added to your `$PATH` environment. `cargo` and `rustup` works closely together, e.g., you may tell `cargo` to use a specific toolchain for the build.
In order to get formatting to work you need to install `rustfmt-nightly`.
```
cargo install rustfmt-nightly
```
There is also another (old) crate named `rustfmt`, that can be compiled with the `stable` Rust compiler. The `rustfmt-nightly` is the *new* and improved formatter, that will eventually replace the old stable `rustfmt` (the generated binaries have the same name so do *not* install the stable version).
# Rust Crates
A crate is a unit of compilation, being either a library or an application. Crates are managed (compiled, installed, removed, updated, etc.) by the [cargo](https://crates.io/) tool.
A *crate* is a unit of compilation, being either a *library* or an application. Crates are managed (compiled, installed, removed, updated, etc.) by the [cargo](https://crates.io/) tool.
`*.toml` files are used throughtout Rust developments for giving configuration (meta) information (essentially replacing the need of Makefiles). The `Cargo.lock` file shows the cashed dependencies (you may delete the `Cargo.lock` file to force updating dependencies, `cargo clean` may not be enough).
Dependencies (may) include a minimal version, eg `itm = "0.1.1"` indicates that at least version `0.1.1` in required (so `0.1.1`, `0.1.2`, `0.2.3` is Ok, while `0.1.0` will not suffice, and a version `1.0.0` would be considered a breaking change (major number changed) and not considered. Rust follows the [semver](http://semver.org/) versioning standard.
# VSCODE support
## RLS
[vscode](https://wiki.archlinux.org/index.php/Visual_Studio_Code) is the official integration test platform for the RLS development, and hence likely also to provide the best user experience.
See [rls](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust) for installing the RLS extension.
You will need to pin the specific toolchain version used, by setting the `"rust-client.channel": "nightly-2017-10-24"` in your `vscode`*user* settings (this will be stored in a file `~/.config/Code/User/settings.json` and used for all your `vscode` projects. Settings may be set individually for each *workspace*, overriding the defaults. To the end of the `"rust-client.channel"` setting, a *workspace* setting would force the specific version, and may not work when code is distributed (as other developers may be on other toolchains).
For RLS to work, `vscode` need a path to the `rls-preview` library (using the environment variable `LD_LIBRARY_PATH`).
You may add this to your `~/.bash_profile`, and start vscode (`code` is the name of the executable) in a new terminal (to ensure that the `LD_LIBRARY_PATH` is correctly set). If `code` is run from your window manager (e.g., `plasma`), make sure that the environment is set correctly.
Under the hood, `rustc --print sysroot` gives you the path to the root of the current toolchain. So its important that the toolchain is set correctsy by `rustup` for this to work.
`*.toml` files are used throughtout Rust developments for giving configuration (meta) information. The `Cargo.lock` file shows the cashed dependencies (you may delete the `Cargo.lock` file to force updating dependencies, `cargo clean may not be enough).
## GIT
You may choose to use the [gitlens](https://github.com/eamodio/vscode-gitlens) extension, to get integrated git support.
Dependencies (may) include a minimal version, eg `itm = "0.1.1"` indicates that at least version `0.1.1` in required (so `0.1.1`, `0.1.2`, `0.2.3` is Ok, while `0.1.0` will not suffice, and a version `1.0.0` would be considered a breaking change (major number changed) and not considered. Rust follows the [semver](http://semver.org/) versioning standard.
\ No newline at end of file
## Native Debug
The [Native Debug](https://github.com/WebFreak001/code-debug) extension allows for debugging Rust application from within `vscode`. Native Debug supports both `lldb` (LLVM) and `gdb` (GNU)
debuggers. For embedded development you will use the latter. See Embedded.md (TODO) for further details.
