Alright. So you want to write Rust? Step one is to get yourself a working environment. This means installing tools. Here's an overview of what you need (more or less in-order):
rustup: this is like
nvm for Node, but officially
supported and really well done! It helps you install and manage Rust compiler
Installing Rustup also installs a valid compiler toolchain, which gives you 3 new commands in total
$ rustup: runs "rustup" to manage your compiler toolchain
$ rustc: which is the Rust compiler. You'll never need to call this because of:
cargois to Rust, what
npmis to Node. It builds, compiles, installs and more. Getting to know
cargowell is usually time well-spent!
cargo-edit provides essential
cargo. In particular: it allows you to run
cargo add which
works somewhat similar to
cargo install works similar to
npm install -g. And when you run
cargo add only your
Cargo.toml file (Rust's
package.json file) is updated
with the right versions. Run
cargo build or
cargo check to actually download
and compile dependencies.
You can install
cargo-edit by running:
$ cargo install cargo-edit
It's a binary component that hooks into the compiler, so it needs to be
$ rustup component add rustfmt
This should take a few seconds on a fast connection. Whenever you update your
rustfmt will also be updated.
Important commands are:
$ cargo fmt # runs rustfmt to format your code $ cargo fmt -- --check # do a dry-run, outputting a diff of changes that would be made $ cargo fmt -- --edition=2018 # pass this flag if you're doing stuff with async/await
clippy is a "linting" tool for Rust,
standard's style lints.
cargo fmt takes care of formatting.
rustc takes care of correctness. But
clippy is in charge of helping you write "idiomatic" Rust.
This doesn't mean every lint in Clippy is perfect. But when you're getting started it can be suuuper helpful to run!
Rust has two language-server implementations:
rust-analyzer. Try using
rust-analyzer first, as it's a far superior experience. But if it doesn't work
for your setup, it's good to be aware of (the much older, kind of unmaintained)
You'll have to figure out for yourself how you want to set this up. But if you're undecided, I've heard VSCode is generally straight forward.
Cargo ships with a
cargo test command, which will run both doctests and files
test/. The Rust book has a whole chapter dedicated to
you should read on this. But it's good to know this is provided for you out of
You can create new projects using
cargo new or
new creates a
init outputs files in the current directory. It's pretty basic,
but it's useful to get started with. If you want to write a library you can pass
either command the
--lib flag. By default you'll create binaries (applications
main function that can be run).
There's also the newer
This is a more powerful version of the built-in
cargo commands, and allows you
to pick from templates. You may not need this if you're just messing around, but
it's probably good to be aware of.
cargo publish works like
npm publish. The central repository is called
crates.io and is very similar to NPM. Importantly it's not
owned by a scummy for-profit company, but is instead part of the Rust project.
If you've built something nice in Rust, consider going ahead and publishing it to Crates.io. All that's needed is a GitHub account to sign up, and you're good to go!
Most docs in JS seem to either be written in a README.md, or as part of some
special website. In Rust documentation is generated automatically using
You can run
$ cargo doc. Every package on crates.io also has
documentation generated for you on docs.rs. It's even
versioned, so you can check out older documentation too. For example: you can
async-std's docs under docs.rs/async-std.
Writing docs in Rust is by using "doc comments" (
/// instead of the regular
// comments). You'll see a bunch in the rest of this guide. Important
documentation commands are:
$ cargo doc # generate docs $ cargo doc --open # generate docs and then open them $ rustup doc --std # open the stdlib docs offline $ rustup doc --book # open the "Rust Programming Language" offline
It can sometimes be tedious to run
cargo check after every change. Which is
cargo-watch exists. You can
install it by running:
$ cargo install cargo-watch
cargo-watch commands are:
$ cargo watch # Run "cargo check" on every change $ cargo watch -x "test" # Run "cargo test" on every change