The basic Rust tooling is composed of three programs:

• cargo: The Rust package manager
• rustc: The Rust compiler
• rustup: The Rust toolchain manager

Most users will never touch (or even see) rustc directly, but will usually use rustup to install it and then let cargo orchestrate the compilation.

Running cargo without any arguments reveals the subcommands it provides:

$ cargo
Rust's package manager 
 
USAGE: 
 cargo [OPTIONS] [SUBCOMMAND] 
 
OPTIONS: 
    -V, --version           Print version info and exit 
        --list              List installed commands 
        --explain <CODE>    Run `rustc --explain CODE` 
    -v, --verbose           Use verbose output (-vv very verbose/build.rs output) 
    -q, --quiet             No output printed to stdout 
        --color <WHEN>      Coloring: auto, always, never 
        --frozen            Require Cargo.lock and cache are up to date 
        --locked            Require Cargo.lock is up to date 
    -Z <FLAG>...            Unstable...

In order to recognize a Rust project, cargo requires its manifest to be present, where most of the other aspects (metadata, source code location, and so on) can be configured. Once this has been done, building the project will create another file: Cargo.lock. This file contains the dependency tree of a project with library versions and locations in order to speed up future builds. Both of these files are essential to a Rust project.

The Cargo.toml file follows—as the name suggests—the TOML structure. It's handwritten and contains metadata about the project as well as dependencies, links to other resources, build profiles, examples, and much more. Most of them are optional and have reasonable defaults. In fact, the cargo new command generates the minimal version of a manifest:

[package]
name = "ch2"
version = "0.1.0"
authors = ["Claus Matzinger"]
edition = "2018"

[dependencies]

There are many more sections and properties, and we will present a few important ones here.

This manifest section is all about metadata for the package, such as name, version, and authors, but also a link to the documentation that defaults to the corresponding page (https://docs.rs/). While many of these fields are there to support crates.io and display various indicators (categories, badges, repository, homepage, and so on), some fields should be filled regardless of whether they are published there, such as license (especially with open source projects).

Another interesting section is the metadata table in package.metadata, because it's ignored by cargo. This means that projects can store their own data in the manifest for project- or publishing-related properties—for example, for publishing on Android's Google Play Store, or information to generate Linux packages.

When you run cargo build, cargo build --release, or cargo test, cargo uses profiles to determine individual settings for each stage. While these have reasonable defaults, you might want to customize some settings. The manifest provides these switches with the [profile.dev], [profile.release], [profile.test], and [profile.bench] sections:

[profile.release] 
opt-level = 3 
debug = false 
rpath = false 
lto = false 
debug-assertions = false 
codegen-units = 16 
panic = 'unwind' 
incremental = false 
overflow-checks = false

These values are the defaults (as of writing this book) and are already useful for most users.

This is probably the most important section for most developers. The dependencies section contains a list of values that represent crate names on crates.io (or your configured private registry) as keys along with the version as values.

Instead of the version string, it's equally possible to provide an inline table as a value that specifies optionality or other fields:

[dependencies]
hyper = "*"
rand = { version = "0.5", optional = true } 

Interestingly, since this is an object, TOML allows us to use it like a section:

[dependencies]
hyper = "*"

[dependencies.rand]
version = "0.5"
features = ["stdweb"]  

Since, in the 2018 edition, the extern crate declarations inside the .rs files are optional, renaming a dependency can be done inside the Cargo.toml specification by using the package property. Then, the specified key can become an alias for this package, like this:

[dependencies]
# import in Rust with "use web::*"
web...

Here is a great quote from the cargo FAQ (https://doc.rust-lang.org/cargo/faq.html) about what the purpose of this file is and what it does:

This serialized state can easily be transferred across teams or computers. Therefore, should a dependency introduce a bug with a patch update, your build should be largely unaffected unless you run cargo update. In fact, it's recommended for libraries to commit the Cargo.lock file to version control to retain a stable, working build. For debugging purposes, it's also quite handy to streamline the dependency tree.

cargo supports a wealth of commands that can be extended easily. It deeply integrates with the project and allows for additional build scripts, benchmarking, testing, and so on.

As the main build tool, cargo does compile and run by way of creating and then executing the output binary (usually found in target/<profile>/<target-triple>/).

What if a library written in a different language is required to precede the Rust build? This is where build scripts come in. As mentioned in the Project configuration section, the manifest provides a field called build which takes a path or name to a build script.

The script itself can be a regular Rust binary that generates output in a designated folder, and can even have dependencies specified in Cargo.toml ([build-dependencies], but nothing else). Any required information (target architecture, output, and so on) is passed into the program using environment variables, and any output for cargo is required to have the cargo:key=value format. Those are picked up by cargo to configure further steps. While the most popular is building native dependencies, it's entirely possible to generate...

As far as commands go, cargo supports test and bench to run a crate's tests. These tests are specified in the code by creating a "module" inside a module and annotating it with #[cfg(test)]. Furthermore, each test also has to be annotated with either #[test] or #[bench], whereas the latter takes an argument to the Bencher, a benchmark runner class that allows us to collect stats on each run:

#![feature(test)] 
extern crate test;

pub fn my_add(a: i32, b: i32) -> i32 {
    a + b
}

#[cfg(test)] 
mod tests { 
    use super::*;
    use test::Bencher;

    #[test] 
    fn this_works() { 
        assert_eq!(my_add(1, 1), 2);
    }
    
    #[test]
    #[should_panic(expected = "attempt to add with overflow")]
    fn this_does_not_work() {
        assert_eq!(my_add(std::i32::MAX, std::i32::MAX), 0);
    }
    
    #[bench]
    fn how_fast(b: &mut Bencher) {
        b.iter(|| my_add(42, 42))
    }
}

After running cargo test, the output is as expected:

Finished dev [unoptimized...

cargo allows the extension of its command-line interface with subcommands. These subcommands are binaries that are called when invoking cargo <command> (for example, cargo clippy for the popular linter).

In order to install a new command (for a particular toolchain), run cargo +nightly install clippy, which will download, compile, and install a crate called cargo-clippy and then put it into the .cargo directory in your home folder. In fact, this will work with any binary that is called cargo-<something> and is executable from any command line. The cargo project keeps an updated list of some useful subcommands in the repository at https://github.com/rust-lang/cargo/wiki/Third-party-cargo-subcommands.

Rust's modules (crates) can easily be packaged and distributed once all the compilation and testing is done, regardless of whether they are libraries or executables. First, let's take a look at Rust binaries in general.

There are executable binaries and libraries in Rust. When these Rust programs use dependencies, they rely on the linker to integrate those so it will work on—at least—the current platform. There are two major types of linking: static and dynamic—both of which are somewhat dependent on the operating system.

Generally, Rust dependencies have two types of linking:

• Static: Via the rlib format.
• Dynamic: Via shared libraries (.so or .dll).

The preference—if a corresponding rlib can be found—is to link statically and therefore include all dependencies into the output binary, making the file a lot larger (to the dismay of embedded programmers). Therefore, if multiple Rust programs use the same dependency, each comes with its own built-in version. It's all about the context though, since, as Go's success has shown, static linking can simplify complex deployments since only a single file has to be rolled out.

There are drawbacks to the static linking approach beyond size: for static libraries, all dependencies have to be of the rlib type, which is Rust's native package format, and cannot contain a dynamic library since the formats (for example, .so (dynamic) and .a (static) on ELF systems) aren't convertible.

For Rust, dynamic linking...

Rust compiles to native code like many other languages, which is great because it expands the available libraries and lets you choose the best technology to solve a problem. "Playing nice with others" has always been a major design goal of Rust.

Interoperability on that level is as simple as declaring the function that you want to import and dynamically linking a library that exports this function. This process is largely automated: the only thing required is to create and declare a build script that compiles the dependency and then tells the linker where the output is located. Depending on what type of library you built, the linker does what is necessary to include it into the Rust program: static or dynamic linking (the default).

If there is only one native library that is to be linked dynamically, the manifest file offers a links property to specify that. Programmatically, it's very easy to interact with these included libraries by using...

The Foreign Function Interface (FFI) is Rust's way of calling into other native libraries (and vice versa) using a simple keyword: extern. By declaring an extern function, the compiler knows that, either an outside interface needs to be bound via the linker (import) or, that the declared function is to be exported so other languages can make use of it (export).

In addition to the keyword, the compiler and linker have to get a hint of what type of binary layout is expected. That's why the usual extern declaration looks as follows:

extern "C" {
    fn imported_function() -> i32;
}

#[no_mangle]
pub extern "C" fn exported_function() -> i32 {
    42
}

This allows a C library function to be called from within Rust. However, there's one caveat: the calling part has to be wrapped in an unsafe section. The Rust compiler cannot guarantee the safety of an external library so it makes sense to be pessimistic about its memory management. The exported function...

Wasm, which WebAssembly is now commonly called, is a binary format meant to complement JavaScript that Rust can be compiled to. The format is designed to run as a stack machine inside several sandboxed execution environments (such as web browsers, or the Node.js runtime) for performance-critical applications (https://blog.x5ff.xyz/blog/azure-functions-wasm-rust/). While this is—as of this writing—in its early stages, Rust and the Wasm target have been used in real-time frontend settings (such as browser games), and in 2018 there was a dedicated working group seeking to improve this integration.

Similar to other targets, such as ARM, the Wasm target is an LLVM (the compiler technology Rust is built on) backend so it has to be installed using rustup target add wasm32-unknown-unknown. Furthermore, it isn't necessary to declare the binary layout (the "C" in extern "C") and a different bindgen tool does the rest: wasm-bindgen, available at https...

The crates.io website (https://crates.io/) provides a huge repository of crates to be used with Rust. Along with discoverability functions, such as tags and search, it allows Rust programmers to offer their work to others.

The repository itself provides APIs to interact with and a wealth of documentation pointers for cargo, crates in general, and so on. The source code is available on GitHub—we recommend checking out the repository for more information: https://github.com/rust-lang/crates.io.

For developers to get their crate into this repository, cargo harbors a command: cargo publish. The command is actually doing more things behind the scenes: first it runs the cargo package to create a *.crate file that contains everything that is uploaded. Then it verifies the contents of the package by essentially running cargo test and checks whether there are any uncommitted files in the local repository. Only if these checks pass does cargo upload the contents of the *.crate file to the repository. This requires a valid account on crates.io (available with your GitHub login) to acquire your personal secret API token, and the crate has to follow certain rules.

cargo is Rust's package manager and build tool that is configurable with a manifest called Cargo.toml. The file is used by cargo to build the desired binary with the specified dependencies, profiles, workspaces, and package metadata. During this process, the package state is saved in a file called Cargo.lock. Thanks to its LLVM frontend, Rust compiles to native code on various platforms including the web (using Wasm)—thus keeping a high degree of interoperabilty. Successfully-built packages can be published on a repository called crates.io, a website that is a central hub for available Rust libraries and binaries.

Before we dive into data structures (starting with lists), the next chapter will introduce the ways Rust stores variables and data in memory, whether to copy or to clone, and what sized and unsized types are.

• What does cargo do?
• Does cargo provide linting support?
• In which cases is the Cargo.lock file important to publish?
• What are the requirements to publish to crates.io?
• What is Wasm and why should you care?
• How are tests organized in a Rust project?

You can refer to the following links for more information on the topics covered in this chapter:

• https://crates.io
• https://doc.rust-lang.org/cargo/
• https://github.com/rustwasm/team
• https://webassembly.org
• https://blog.x5ff.xyz/blog/azure-functions-wasm-rust/