about
10/31/2024
Help: Rust Cargo

Help: Rust Cargo

development tools for Rust: cargo, clippy, fmt, doc

About
click header to toggle Rust Explorer

Synopsis:

Cargo is part of the Rust tool-chain, providing project creation, build, execution, code formatting, and documentation. It is easy to use and has good documentation

1.0 Cargo Package Manager

Visual Studio Code is an effective tool for adding files and editing code. Opening a terminal panel in the editor supports command line builds, execution, formatting, and testing using the Cargo package manager. Figure 1. VS Code with Terminal Common cargo commands are:
  • cargo new mypkg
    Create directory with cargo.toml file and src directory
  • cargo run
    Build and execute binary created from src::main.rs
  • cargo test
    Run unit tests associated with src::lib.rs
  • cargo run --example test1
    Execute examples::test1.rs built with src::lib.rs
  • cargo clippy
    Evaluate package's code style and complexity
  • cargo fmt
    Reformat local source code files according to Rust community accepted rules.
Cargo is powerful but still quite easy to use, especially within a VS Code terminal panel, as shown in Figure 4. For the last two years I've used VS Code and Cargo to build virtually all of the code shown in my github repositories. That includes projects with multiple packages and remote crates from crates.io. The Cargo.toml file provides a declarative interface to define dependencies on muliple local libraries as well as remote crates. You can view more details about cargo commands in the dropdown below.
Cargo Commands 
Cargo Command Action
Selection of frequently used cargo commands and options. To see all: use cargo help
new Create a new package in a new folder. Folder contains cargo.toml file and src directory.
syntax:  cargo new name [options] [path]
options: --bin, --lib, --name, (-v, --verbose), (-q, --quiet), (-h, --help)
example: cargo new mypkg --bin
Creates new package in subdirectory mypkg. src contains code for hello world executable.
init Create a new package in an existing folder. Folder contains cargo.toml file and src directory.
syntax:  cargo init name [options] [path]
options: --bin, --lib, --name, (-v, --verbose), (-q, --quiet), (-h, --help)
example: cargo init mypkg --lib
Creates new package in existing subdirectory mypkg. src contains code for library.
build, b Compile local packages and all their dependencies that have changed since last build.
syntax:  cargo build [options]
options: (-d, --debug), (-r, --release), --example name, (-v, --verbose), (-q, --quiet)
example: cargo build --example test1
Builds test1.rs in examples subdirectory (sibling of src)
check, c Same as build but omits code generation.
run, r Build local packages and their dependencies that have changed since last build and execute bin file.
syntax:  cargo run [options] [--args]
options: (-d, --debug), (-r, --release), --example name, (-v, --verbose), (-q, --quiet)
example: cargo run
Builds main.rs in src subdirectory and its dependencies, and runs binary
example: cargo run --example test1
Builds lib.rs and its dependencies in src subdirectory, test1.rs in examples subdirectory (sibling of src) and runs binary
test, t Execute package unit, integration, and documentation tests.
syntax:  cargo test [testname] [--test-options]
options: Use cargo help test
example: cargo test
clean Remove build products
syntax: cargo clean [options]
options: Use cargo help clean
doc, d Build documentation for local package and all dependencies.
syntax: cargo doc [options]
options: Use cargo help doc
clippy Style and complexity checker. Guidance to write idiomatic code.
syntax: cargo clippy [options]
options: Use cargo help clippy
fmt Runs rustfmt on all bin and lib files in current package.
syntax: cargo fmt
common option: create rustfmt.toml file with tab_spaces = 2 to change indent width

2.0 Rust Development Process using Cargo:

The table below captures a process for developing code using VS Code and Cargo.
Topic Rust
Installation Rust: cargo, rustc, clippy
Download Rust.
That includes rustc - the rust compiler, cargo - a package manager, and other tools like clippy. This works for Windows and Linux.
Install Rust pluggin, RLS, from the pluggin dropdown in VSCode's left menu bar. That supports intellisence and debugging. If you have any problems with that, this tutorial may help: VSCode with Rust.
Work Flow
[ Example: Bin Project ].
[ Example: Lib Project ].
Creating Projects:
In VS Code, open the parent folder where you want to create a new Rust project.
You create a binary project with the terminal command:
cargo new TestPkg --name test_pkg
That creates a new directory TestPkg with a cargo.toml metadata file and /src folder with hello world Rust code in main.rs. Rust uses the naming conventions:
  1. snake_case:
    Rust wants project names, test_pkg, and data names, my_data, to be snake_case, e.g., all lower case, words separated with an underscore.
  2. CamelCase:
    Rust wants type names Vec<String>, MyPoint, ... to be CamelCase, e.g. each word in a name is capitalized with all the other characters lower case.
That's why the new command ends with --name test_pkg. If you don't use a snake_case name you will repeatedly get warnings about naming formats.
Now you can open the new folder from the File menu and run or start debugging. when you don't need to debug just issue the command:
cargo run test_pkg
in the terminal.
You create a library with the terminal command:
cargo new TestLib --lib --name test_lib
cargo builds the library starter code with test fixtures for unit tests. Once you have some library code and corresponding tests, you run tests with the terminal command:
cargo test
If you manually create an /examples folder as a sibling to the /src folder, you can put demonstration code that uses the library and displays results on the termianl. To do that use the command:
cargo run --example test1
where test1.rs is the demonstration code inside /examples. Two things to note here:
  1. The directory name is examples (plural) but the option is --example (singular).
  2. The file name is test1.rs but the option value is test1 (no extension).
Building Applications Figure 4. Application Structure When you build applications, you will probably factor them into several libraries and an executive. Figure 4. presents an example.
Each library has:
  1. A library directory containing a cargo.toml file, a src directory containing library code, and an examples directory containing one or more test and demonstration files, each with a main function.
  2. Cargo.toml file contains metadata about the library and a list of dependencies, if any. That dependency list helps cargo automatically bind dependencies to the library.
  3. lib.rs file that contains source code for the library and usually a set of configured tests checking that the library maintains its design invariants.
    You run those tests with the command:
    cargo test
    Run from the terminal in the library project directory (where the cargo.toml file resides).
  4. One or more test and demonstration files, each with a main function, test1.rs, ... placed in an "examples" directory, a sibling of "src". These files bind to the library and provide visual evidence that library's operations are as expected. You run demonstration tests with the command:
    cargo run --example test1
The Application has an Executive directory with:
  1. A cargo.toml file listing the dependencies of the executive on Lib #1 and Lib #2.
    [dependencies]
    lib1_name = { Path = "../Lib1" }
    lib2_name = { Path = "../Lib2" }
  2. An executive file with a main function and, at the top:
    use lib1_name::*;
    use lib2_name::*;
    This gives executive code access to all the public facilities in both libraries.
The Cargo book has examples of this with several additional options.
Checking code style with clippy Coming soon
Formatting code with fmt Coming soon
Building documentation with doc Coming soon
  Next Prev Pages Sections About Keys