Skip to content

Latest commit

 

History

History
219 lines (152 loc) · 8.51 KB

overview.md

File metadata and controls

219 lines (152 loc) · 8.51 KB
Raw

Rust tools

Building Rust programs

rustc - the compiler

You'll probably never use the compiler directly; the usual way to build a Rust program is to use Cargo. Part of the Rust distribution.

Cargo

Cargo is Rust's package manager and build system. It is distributed with Rust by default so you don't need to use it.

Rustup

Rustup is a tool for installing Rust and managing Rust toolchains, for example for different channels (nightly, beta, etc.) or target platforms for cross- compilation.

Xargo

Xargo is a tool to help with cross-compilation. It builds and manages versions of the standard libraries, and manages Cargo targets. It is a drop-in replacement for Cargo, e.g., you use xargo build instead of cargo build.

cargo watch

A tool that watches the disk for changes and starts a build when you change a file in your project. Run with cargo watch.

IDEs and editors

Many editors have some Rust support, from basic syntax highlighting to full IDE features.

For IDE support we recommend either VSCode with the Rust Language Server or IntelliJ. The Rust Language Server is an editor-independent service for providing IDE functionality using the Language Server Protocol. Any editor can be an RLS client and we hope many editors will take advantage of it.

Visual Studio Code

Visual Studio Code is a cross-platform, open source IDE from Microsoft. It has very basic support (syntax highlighting) out of the box. For better Rust support, install the Rust (RLS) plugin:

The RLS

The power behind the above VSCode extension is the RLS. It interacts with the compiler to provide information about Rust programs to IDEs and editors. You probably don't want to use it directly, but rather via an editor extension.

IntelliJ

Rust support in IntelliJ is provided by JetBrains via an open source plugin, written in Kotlin. It uses its own Rust programming language model instead of RLS, so some features available in RLS might not be available in IntelliJ and vice verse.

Other editors

Many editors have plugins or extensions that provide some degree of support (syntax highlighting, snippets, etc.). Racer is a tool for providing code completion and 'goto def' features. It uses it's own parsing and type inference, so is very quick, but sometimes incomplete. There are extensions using Racer for many editors.

Debugging and profiling

TODO

  • gdb - versions, script?
  • lldb
  • vs

Formatting

Rustfmt is a tool for automatically formatting Rust code. It enforces the officially recommended Rust style, or can be configured to your taste. It is used by the RLS, so if you're using an RLS-powered IDE, you don't separetly need Rustfmt. If you're not, you can use it with Cargo (cargo fmt) or standalone (rustfmt).

Working with other languages

TODO

Linting

Clippy

Clippy is a collection of lints to catch common mistakes and improve your Rust code. It also covers code style issues that aren't just syntactical and require type information. It comes as a compiler plugin and as a cargo subcommand (cargo clippy).

TODO

  • sanitisers

Documentation and code exploration

Rustdoc

Rustdoc generates API documentation for Rust crates. You probably don't need to use rustdoc directly (instead going through cargo doc). Accepts a crate and generates HTML pages for its public documentation. Can also execute code blocks within the documentation as tests. Part of the normal Rust distribution.

  • Source code (part of the Rust compiler source code)
  • Install using Rustup (see above). Installed by default when you get rustc.

Rustdoc 2

In-progress reimplementation of rustdoc using the RLS as a backend (rather than compiler-internal libraries). Plans include JSON output, multiple pluggable "frontends" to render as different formats, and separating out the HTML design to allow more contributors to work on the site design.

The initial plans for the new rustdoc were discussed during the dev-tools meeting on 2017-05-30.

TODO

  • rustw
  • docs.rs

Versioning

rust-semverver

Rust-semverver is a tool to verify semantic versioning in Rust library crates. It compiles two given versions of a crate together and uses the compiler's internals to match up items and to determine changes, classifying them according to the semver specification applied to the Rust typesystem, as outlined in the API evolution RFC.

Testing, etc.

TODO

  • test, bench
  • cargo fuzz
  • compiletest
  • coverage