This chapter is from the book
This chapter is from the book
This chapter is from the book
Cargo
You can use the cargo tool to compile Rust crates and create binaries. This is in lieu of using the rustc compiler directly. cargo is a versatile tool that can perform various tasks, including creating and managing packages, compiling binaries, maintaining a secure environment, and managing dependencies. For compilation, cargo delegates to the rustc compiler.
Because of the flexibility of this tool, Rustaceans often prefer cargo, instead of rustc, for compilation. In addition, this means learning only one command-line interface instead of two. Since most Rustaceans are probably using cargo already for something, such as creating new packages, it is simpler not to switch to a different tool. Keep in mind, though, that the rustc tool will continue to be used, just indirectly.
The cargo new command, shown next, creates a new package for either an executable or library crate. The default is an executable crate. A library crate can be created with the --lib option.
cargo new name
The cargo new command also creates a directory structure for the new package. Initially, this includes a root directory and src subdirectory. The tool will add more directories as needed. In the root directory are two files: .gitignore and cargo.toml. Either the main.rs or lib.rs crate is placed in the src subdirectory, depending on whether this is an executable or library package, respectively.
You can also create a package within an existing directory. From that directory, issue the following command, and a package is created at that location:
cargo init
The .gitignore file lists directories and files excluded from GitHub. This initially includes the target subdirectory, which contains the compiled binaries, and the cargo.lock file.
Cargo.toml is the manifest and configuration file for the package. The TOML suffix is a reference to Tom’s Obvious Minimal Language and is a standard format for a readable configuration file. Cargo.toml contains important configuration details about the package, including the name of the package. The cargo new command creates the initial cargo.toml, as shown in Listing 2.2.
Code Listing 2.2. Sample cargo.toml file
[package]
name = "packagename"
version = "0.1.0"
edition = "2021"
# See more keys and their definitions at https://doc.rust-
lang.org/cargo/reference/manifest.html
[dependencies]
Within the cargo.toml file, the following information is presented:
name: The package name is derived from the cargo new command.
version: The three-part semantic version (major.minor.patch).
edition: The current Rust language edition.
dependency: Dependencies are documented within this section.
comments: The # character indicates a comment to the end of the line.
The cargo new command creates the cargo.toml file. Information can be inserted manually in the TOML file, such as license information, a brief description, and the location of the documentation.
In addition to the cargo.toml file, the cargo new command creates a source file in the src subdirectory. For an executable crate, this is the main.rs file that contains sample code for a “Hello, World” application. Of course, feel free to replace this with your actual code. Listing 2.3 shows the main.rs file generated by the cargo tool.
Code Listing 2.3. Source file generated by the Cargo tool
fn main() {
println!("Hello, world!");
}
You can compile the crate with the following command and create a binary executable:
cargo build
This command must be executed from within the package. The cargo build command performs an incremental build. Changes to the crate, modifying the dependencies in cargo.toml, and other reasons may force a full build instead of an incremental one.
The cargo build command creates a packageroot/target directory. Within that directory, a debug or release directory is created, depending on the type of the build target for the binary. The cargo build command defaults to building a debug target. A debug binary has few, if any, optimizations, which is ideal for debugging. The release binary is most often optimized for either performance or size. The cargo build --release command creates a release binary that is placed in the release directory.
You can run an executable crate with the following command:
cargo run
This must also be done from within the package. If the binary is not already built, cargo build will be done first. For this reason, some skip the separate build step entirely for executable crates and rely entirely on the cargo run command.