using-cargo.md

Using Cargo

Crates and Packages

• Rust code is arranged into packages
• a package is described by a Cargo.toml file
• building a package can produce a single library, and 0 or more executables
  • these are called crates
  • unlike C/C++ compilers that compile code file by file, rustc treat all files for a crate as a single compilation unit
• Cargo calls rustc to build each crate in the package.

Cargo

• standard build toolchain for Rust projects
• shipped with rustc

What Cargo does

• resolves and installs project dependencies
• runs rustc to compile your code
• runs a linker to produce libraries and executables
• runs tests and benchmarks
• builds documentation and runs documentation tests
• runs additional tools like code formatter and linter
• can be extended with additional custom commands

Cargo does Everything!

Cargo commands

• cargo new my-app
• cargo run - runs a debug build of your program, builds it if necessary
• cargo fmt - formats your code
• cargo check - only reports errors, doesn't actually compile your code
• cargo clippy - runs a linter
• cargo test - builds your project if necessary and runs tests
  • by default runs unit tests, integration tests, and documentation tests
  • you can select which tests to run
• cargo build --release - produces an optimized version of your application or library

Cargo commands (cont)

There are many more!

• cargo bench - builds an optimized version of your project and runs benchmarks
• cargo doc --open - builds documentation for your project and all its dependencies and opens it in a browser
• cargo run --example ... - runs an example from your examples/ directory

See Cargo Book for more.

Cargo command arguments

Most cargo commands accept a few common arguments:

• +toolchain
• --target
• --features, --all-features, and --no-default-features
• --timings

Putting it all together:

cargo +nightly run --target x86_64-apple-darwin --features "a b c dependency/feature" --timings

• use nightly Rust
• enable features a, b, c, and a feature feature of a dependency crate
• (assuming we use Apple Silicon computer) build a macOS executable for x86 processor and run it using built-in emulation (Rosetta2)
• collect statistics during the build process and generate a report

Features

• allows conditional compilation
  • support for different operating systems
  • adapters for different libraries
  • optional extensions
• can expose features from transitive dependencies

Using Features

• in code:

  #[cfg(feature = "json")]
  mod json_support;
  

• in Cargo.toml

  [features]
  json = [] # list of features that this feature depends on
  default = [] # "json" feature is not enabled by default

• when someone uses your dependency

  my-lib = { version: "1.0.0", features = ["json"] }

Anatomy of Rust package

cargo new hello-world

├── Cargo.lock
├── Cargo.toml
└── src/
    └── main.rs

Anatomy of Rust package

├── Cargo.lock
├── Cargo.toml
├── build.rs
├── src/
│   ├── lib.rs
│   ├── main.rs
│   ├── ...
│   └── bin/
│       ├── additional-executable.rs
│       └── multi-file-executable/
│           ├── main.rs
│           └── ...
├── benches/
│   └── ...
├── examples/
│   └── ...
└── tests/
    ├── some-integration-tests.rs
    └── multi-file-test/
        ├── main.rs
        └── ...

Cargo.toml - A manifest file

[package]
name = "tcp-mailbox"
version = "0.1.0"

[dependencies]
async-std = "1" # would also choose 1.5
clap = "2.2" # would also choose 2.3