2 Project management with Cargo

$ cargo help
Rust's package manager
 
USAGE:
    cargo [+toolchain] [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
        --offline           Run without accessing the network
    -Z <FLAG>...            Unstable (nightly-only) flags to Cargo, see
    'cargo -Z help' for details
    -h, --help              Prints help information
 
Some common cargo commands are (see all commands with --list):
    build, b    Compile the current package
    check, c    Analyze the current package and report errors, but don't
    build object files
    clean       Remove the target directory
    doc         Build this package's and its dependencies' documentation
    new         Create a new cargo package
    init        Create a new cargo package in an existing directory
    run, r      Run a binary or example of the local package
    test, t     Run the tests
    bench       Run the benchmarks
    update      Update dependencies listed in Cargo.lock
    search      Search registry for crates
    publish     Package and upload this package to the registry
    install     Install a Rust binary. Default location is $HOME/.cargo/bin
    uninstall   Uninstall a Rust binary
 
See 'cargo help <command>' for more information on a specific command.

$ cargo new dolphins-are-cool
     Created binary (application) `dolphins-are-cool` package

$ cd dolphins-are-cool/
$ tree
.
├── Cargo.toml
└── src
    └── main.rs
 
1 directory, 2 files

$ cargo run
   Compiling dolphins-are-cool v0.1.0 (/Users/brenden/dev/dolphins-are-cool)
    Finished dev [unoptimized + debuginfo] target(s) in 0.59s
     Running `target/debug/dolphins-are-cool`
Hello, world!                                   ❶

$ cargo new narwhals-are-real --lib
     Created library `narwhals-are-real` package
$ cd narwhals-are-real/
$ tree
.
├── Cargo.toml
└── src
    └── lib.rs
 
1 directory, 2 files

$ cargo test
    Finished test [unoptimized + debuginfo] target(s) in 0.00s
     Running target/debug/deps/narwhals_are_real-3265ca33d2780ea2
 
running 1 test
test tests::it_works ... ok
 
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out;
finished in 0.00s
 
   Doc-tests narwhals-are-real
 
running 0 tests
 
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out;
finished in 0.00s

# Runs tests with stable channel:
$ cargo +stable test
...
# Runs tests with nightly channel:
$ cargo +nightly test
...

# Only applies to the current directory and its children
$ rustup override set nightly

# Adds the rand crate as a dependency to the current project
$ cargo add rand

$ cargo new patch-num-cpus
...
$ cd patch-num-cpus
$ cargo run
...
Hello, world!

[dependencies]
num_cpus“= "”.0"

fn main() {
    printl“!("There are {} C”Us", num_cpus::get());
}

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/patch-num-cpus`
There are 4 CPUs

$ cargo new num_cpus --lib
...

pub fn get() -> usize {
    100                  ❶
}

[dependencies]
num_cpus = { path = "num_cpus" }

$ cargo run
   Compiling patch-num-cpus v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 0.33s
     Running `target/debug/patch-num-cpus`
There are 100 CPUs

[dependencies]
num_cpus = { git = "https://github.com/brndnmtthws/num_cpus",
  rev = "b423db0a698b035914ae1fd6b7ce5d2a4e727b46" }

[patch.crates-io]
libc = { git = "https://github.com/rust-lang/libc", tag = "0.2.88" }

$ otool -L target/debug/zlib-wrapper
target/debug/zlib-wrapper:
    /usr/lib/libz.1.dylib (compatibility version 1.0.0, current version
  1.2.11)
    /usr/lib/libiconv.2.dylib (compatibility version 7.0.0, current version
  7.0.0)
    /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version
  1292.60.1)
    /usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version
  1.0.0)

$ rustup target list
rustup target list
aarch64-apple-darwin
aarch64-apple-ios
aarch64-fuchsia
aarch64-linux-android
aarch64-pc-windows-msvc
..

$ rustup target add aarch64-apple-darwin
info: downloading component ‘rust-std’ for ‘aarch64-apple-darwin’
info: installing component ‘rust-std’ for ‘aarch64-apple-darwin’
info: using up to 500.0 MiB of RAM to unpack components
 18.3 MiB /  18.3 MiB (100 %)  14.7 MiB/s in  1s ETA:  0s
$ cargo build --target aarch64-apple-darwin
...
    Finished dev [unoptimized + debuginfo] target(s) in 3.74s

$ ./target/aarch64-apple-darwin/debug/simple-project
-bash: ./target/aarch64-apple-darwin/debug/simple-project: Bad CPU type in
executable

$ RUSTFLAGS="-C target-feature=+crt-static" cargo build
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s

$ rustup target add x86_64-unknown-linux-musl    ❶
...
$ RUSTFLAGS="-C target-feature=+crt-static" cargo build --target
x86_64-unknown-linux-musl                        ❷
...

[target.x86_64-pc-windows-msvc]
rustflags = ["-Ctarget-feature=+crt-static"]

$ cargo new rustdoc-example --lib
     Created library `rustdoc-example` package

pub fn mult(a: i32, b: i32) -> i32 {
    a * b
}
 
#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn it_works() {
        assert_eq!(2 * 2, mult(2, 2));
    }
}

$ cargo doc
 Documenting rustdoc-example v0.1.0
 (/Users/brenden/dev/code-like-a-pro-in-rust/code/c2/2.8/rustdoc-example)
    Finished dev [unoptimized + debuginfo] target(s) in 0.89s

//! # rustdoc-example                                                     ❶
//!                                                                       ❶
//! A simple project demonstrating the use of rustdoc with the function   ❶
//! [`mult`].                                                             ❶
 
#![warn(missing_docs)]                                                    ❷
 
/// Returns the product of `a` and `b`.                                   ❸
pub fn mult(a: i32, b: i32) -> i32 {
    a * b
}

[package]
name = "dryoc"
documentation = "https://docs.rs/dryoc"

//! # Example
//!
//! -----
//! use rustdoc_example::mult;
//! assert_eq!(mult(10, 10), 100);
//! -----

cargo test
   Compiling rustdoc-example v0.1.0
   (/Users/brenden/dev/code-like-a-pro-in-rust/code/c2/2.8/rustdoc-example)
    Finished test [unoptimized + debuginfo] target(s) in 0.42s
     Running target/debug/deps/rustdoc_example-bec4912aee60500b
 
running 1 test
test tests::it_works ... ok
 
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out;
  finished in 0.00s
 
   Doc-tests rustdoc-example
 
running 1 test
test src/lib.rs - (line 7) ... ok
 
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out;
  finished in 0.23s

mod private_mod {
  // ...              ❶
}
pub mod public_mod {
  // ...              ❷
}

mod private_mod;
pub mod public_mod;

mod outer_mod {
  mod inner_mod {
    mod super_inner_mod {
      ...
    }
  }
}

use serde::ser::{Serialize, Serializer};   ❶

$ tree .
.
├── Cargo.lock
├── Cargo.toml
└── src
    ├── lib.rs
    ├── outer_module
    │   └── inner_module
    │       ├── mod.rs
    │       └── super_inner_module.rs
    └── outer_module.rs
 
3 directories, 6 files

mod outer_module;

mod inner_module;

mod super_inner_module;

$ cargo new workspaces-example
     Created binary (application) `workspaces-example` package
$ cd workspaces-example

$ cargo new subproject --lib

$ tree
.
├── Cargo.toml
├── src
│   └── main.rs
└── subproject
    ├── Cargo.toml
    └── src
        └── lib.rs
 
3 directories, 4 files

[dependencies]
subproject = { path = "./subproject" }

[workspace]
members = ["subproject"]

pub fn hello_world() -> String {
    String::from("Hello, world!")
}

fn main() {
    println!("{}", subproject::hello_world());
}

$ cargo run
   Compiling subproject v0.1.0
   (/Users/brenden/dev/code-like-a-pro-in-rust/code/c2/2.9/workspaces-examp
   le/subproject)
   Compiling workspaces-example v0.1.0 (/Users/brenden/dev/
   ➥ code-like-a-pro-in-rust/code/c2/2.9/workspaces-example)
    Finished dev [unoptimized + debuginfo] target(s) in 0.85s
     Running `target/debug/workspaces-example`
Hello, world!

$ cargo new build-script-example
$ cd build-script-example

const char *hello_world(void) {
    return "Hello, world!";
}

[dependencies]
libc = "0.2"
[build-dependencies]
cc = "1.0"

fn main() {
    println!("cargo:rerun-if-changed=src/hello_world.c");    ❶
    cc::Build::new()                                         ❷
        .file("src/hello_world.c")
        .compile("hello_world");
}

use libc::c_char;
use std::ffi::CStr;
 
extern "C" {
    fn hello_world() -> *const c_char;    ❶
}
 
fn call_hello_world() -> &'static str {   ❷
    unsafe {
        CStr::from_ptr(hello_world())
            .to_str()
            .expect("String conversion failure")
    }
}
 
fn main() {
    println!("{}", call_hello_world());
}

$ cargo run
   Compiling cc v1.0.67
   Compiling libc v0.2.91
   Compiling build-script-example v0.1.0 (/Users/brenden/dev/
   code-like-a-pro-in-rust/code/c2/2.10/build-script-example)
    Finished dev [unoptimized + debuginfo] target(s) in 2.26s
     Running `target/debug/build-script-example`
Hello, world!