Cargo is Rust's build system and package manager.
Publicly available crates can be found at crates.io!
$ cargo build compiles your code in ./srs and saves the results to ./target/debug by default. This command also creates a Cargo.lock file in the base directory. This file is used to keep track of the exact versions of dependencies in the project.
Flags:
--release: Compiles the source code with optimizations. Saves the results to target/release$ cargo check makes sure your project contains valid Rust code (parses the code and checks for syntax errors).
Clippy is a linter for Rust code. Use $ cargo clippy to lint your code. Use $ rustup component add clippy to install Clippy first.
Rust comes with documentation comments. To use documentation comments, start a line with ///. These comments support markdown notation and can be converted to HTML using cargo doc. The documents will be saved to target/doc
The other documentation comment is //!. This type of comment is used to add comments to what it is in (like crates) as opposed to what is after the comment (a function). These are common at the beginning of a file.
Example (in math/src/lib.rs):
//! # Math
//!
//! `math` is a collection of mathematical functions
/// Squares the given number
///
/// # Examples
///
/// ```
/// let square = math::square(5);
///
/// assert_eq!(25, square);
/// ```
/// ```
/// let square1 = math::square(1);
///
/// asswert_eq!(1, square1);
/// ```
pub fn square(x: i32) -> i32 {
x * x
}
--open: Build and open the HTML documentationErrors: If a Result is returned, what kind of errors might occur and how are they causedExamples: Example usagePanics: What scenarios causes the function to panicSafety: If unsafe is used, explain why and the variants the caller must upholdcargo test actually tests the code left in documentation comments!
Cargo.lock is used in conjunction with your dependences in Cargo.toml. The Cargo.lock file locks in the version of your dependences when $ cargo build was first executed with the dependency. With this lock, if a newer minor release or other release for the dependency is added, your project will continue to use the old release.
Use $ cargo new <project_name> to create a new Rust project. This command will create a nested directory containing a Cargo.toml file and a srs/ directory containing a basic source file. In addition, it will initialize a git repository for the project.
The Cargo.toml file is Cargo's configuration file for packages. In Rust, packages of code are called "crates".
Flags:
--lib: Initialize a library (make src/lib.rs)$ cargo run both compiles your rust code and runs the resulting executable.
Fix rust code (i.e. compiler warnings) using $ cargo fix.
You can automatically format rust code using $ cargo fmt. You will first need to install rustfmt using $ rustup component add rustfmt.
Cargo has a tests suit. To run, use cargo test.
cargo test accepts two types of parameters separated by --. The flags that go before the -- are for cargo test while the flags that go after -- are for your test suit. For help you can either do cargo test --help for help with cargo test or cargo test -- --help for help with what you can pass to your test suit.
By default, tests run in parallel, so it can be dangerous if they use the same resources, like an opened file. To make them run in sequential order, use cargo test -- --test-threads=1.
By default, output to stdout from your code for tests will not be shown. To show test output do cargo test -- --show.
To run a subset of the test suit, use cargo test <function name match> where cargo will run any tests that have your inputted string in the test function name.
To ignore some tests add #[ignore] before the test function but after #[test]. These tests will be ignored unless you do cargo test -- --ignored.
Cargo.toml is Cargo's configuration file for packages. It contains several sections.
The dependencies section ([dependencies]) contains the dependencies for the package. For example:
[dependencies]
rand = "0.8.3"This will import the rand external crate with the version number of 0.8.X where "X" is 3 or greater. The last number if considered a minor release. Any release with the same first and secondary number will have the same public API and will be compatible.
Profiles allows you to customize how your code is compiled during development and release times. Example:
[profile.dev]
opt-level = 0
$ cargo update is used to update the crates in the Cargo.lock file. It uses the dependencies found in the Cargo.toml file and updates the Cargo.lock file to the newest appropriate dependency.