Rust cargo

cargo is rust's build system, package manager, test-runner, and lots more.
it's sort of rust's swiss army knife.

Documentation

book: cargo reference	https://doc.rust-lang.org/cargo/reference/index.html
Cargo.toml docs	https://doc.rust-lang.org/cargo/reference/manifest.html
cargo commands	https://doc.rust-lang.org/cargo/commands/index.html
man cargo	https://man.archlinux.org/man/extra/rust/cargo.1.en

Global Locations

~/.cargo/bin/*	cargo installed executables
~/.config/registry/*	cached cargo registry indexes
~/.cargo/config.toml	global config
~/.config/credentials.toml	cargo registry credentials

Project Locations

${PROJECT}/Cargo.toml	project config
${PROJECT}/Cargo.lock	frozen package versions

Usage

cargo commands

https://doc.rust-lang.org/cargo/commands/index.html

Project Management

cargo new my_project   # create project

# build
cargo build            # compile project (for testing)
cargo run              # compile/run executable
cargo check            # check project can build, without building
cargo build --release  # build w/ optimizations (more performant)
cargo test             # run tests

# dependencies
cargo update           # update all packages
cargo update -p regex  # update only 'regex' package

Publishing Packages

In order to publish a crate, you need a crates.io account.

# 1. manually create an account on https://crates.io

# 2. retrieve API key from https://crates.io/me

# 3. register your API key locally
cargo login ${your_api_key}

Now you can publish a crate using cargo publish.
you'll need to update the version between each publish.

cargo publish             # publish crate version
cargo yank --vers 1.1.1   # mark version bad, disallowing new users from requesting this version

Project Configuration

Basics

# ${PROJECT}/Cargo.toml

[package]
name = "hello_cargo"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
edition = "2018"

[dependencies]
time = "0.1.12"
regex = "0.1.41"
rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }

Dependencies

Intro	https://doc.rust-lang.org/cargo/guide/dependencies.html
Dependencies	https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html
Overriding Dependencies	https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html
Optional Dependencies	https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies

Add Dependency

• To add a dependency, add it to your Cargo.toml under [dependencies].
• Then run cargo build

# ...
[dependencies]
rand = "0.8.5"

cargo build  # fetch packages and compile

Update Dependency

First, update the version-request in your Cargo.toml

[dependencies]
rand = "0.9.0"

Then cargo build

cargo update # ignore cargo.toml

Version Requests

# ${PROJECT}/Cargo.toml

[dependencies]
time = "0.1.12"
foo = "^0.8.5"   # 0.8.5 <= 0.9
rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }
gif = { version = "0.11.1", optional = true }

• Optional dependencies define features of the same name

Features

features

https://doc.rust-lang.org/cargo/reference/features.html

Features can be defined, and enabled/disabled at build time.

Define features in your Cargo.toml

# ${PROJECT}/Cargo.toml

[features]
lua = []
python = []
airline = ["python"]

#[cfg(feature = "python")]
pub mod embed_python;

Workspaces

workspaces

https://doc.rust-lang.org/cargo/reference/workspaces.html