From f99f113aed7402cf5ce0010fba52a3bd9b1f8f06 Mon Sep 17 00:00:00 2001 From: Per <Per Lindgren> Date: Mon, 30 Oct 2017 11:27:20 +0100 Subject: [PATCH] Echosystem with vscode --- doc/Ecosystem.md | 75 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 64 insertions(+), 11 deletions(-) diff --git a/doc/Ecosystem.md b/doc/Ecosystem.md index fdc4820..8f2b9f6 100644 --- a/doc/Ecosystem.md +++ b/doc/Ecosystem.md @@ -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: +``` +rustup default nightly-2017-10-22-x86_64-unknown-linux-gnu +``` +and get information on the status of `rustup` +``` +rustup show +``` + +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: +``` +rustup default nightly-2017-10-22-x86_64-unknown-linux-gnu +rustup component add rls-preview +rustup component add rust-analysis +rustup component add rust-src +``` +`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`). +``` +export LD_LIBRARY_PATH=$(rustc --print sysroot)/lib +``` +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. \ No newline at end of file -- GitLab