Cargo

    Published: 2023-06-16
    Updated: 2024-08-22

    Configuring Cargo 🔗

    See the Cargo Reference

    Frequently Used Commands and arguments 🔗

    Source: https://doc.rust-lang.org/cargo/commands/index.html

    • doc
      • --document-private-items
      • --no-deps
      • --target-dir
      • --open
    • run
    • test
      • -- --ignored (Works with #[ignore] see rust reference)
      • -- --test-threads 1
    • tree
      • -e features
      • -f "{p} {f}"
      • -e features -i foo

    Cargo Environment Variables 🔗

    For Crates 🔗

    Source: https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates

    To use environment variables provided by cargo use env!().

    Example

    println!("{}", env!("CARGO_PKG_NAME"));

    Specifying dependencies 🔗

    Using Git 🔗

    Source: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories

    Example

    [dependencies]
regex = { git = "https://github.com/rust-lang/regex.git", branch = "next" }

    Adding Feature flag to a library 🔗

    Source: https://doc.rust-lang.org/cargo/reference/features.html

    Example of defining a feature

    [features]
default = ["ico", "webp"]
avif = ["dep:ravif", "dep:rgb"]
bmp = []
gif = ["dep:gif"]
png = []
ico = ["bmp", "png"]
# Defines a feature named `webp` that does not enable any other features.
webp = []

    Optional dependency

    [dependencies]
gif = { version = "0.11.1", optional = true }
ravif = { version = "0.6.3", optional = true }
rgb = { version = "0.8.25", optional = true }

    Example of conditionally compiling based on feature

    // This conditionally includes a module which implements WEBP support.
#[cfg(feature = "webp")]
pub mod webp;

    Mutually Exclusive Feature Flags 🔗

    Source: https://doc.rust-lang.org/cargo/reference/features.html#mutually-exclusive-features

    TLDR: Avoid using mutually exclusive features see source above for options to work around it otherwise detect it at compile time and provide an error message instead of waiting for duplicated functions to stop the compile.

    #[cfg(all(feature = "foo", feature = "bar"))]
compile_error!("feature \"foo\" and feature \"bar\" cannot be enabled at the same time");

    Patch a crate 🔗

    Source: https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#testing-a-bugfix

    The source is sufficiently terse that I don’t find value in extracting relevant parts here other than pointing out the following:

    The way [patch] works is that it’ll load the dependency at ../path/to/uuid and then whenever crates.io is queried for versions of uuid it’ll also return the local version.

    This means that the version number of the local checkout is significant and will affect whether the patch is used. Our manifest declared uuid = “1.0” which means we’ll only resolve to >= 1.0.0, < 2.0.0, and Cargo’s greedy resolution algorithm also means that we’ll resolve to the maximum version within that range. Typically this doesn’t matter as the version of the git repository will already be greater or match the maximum version published on crates.io, but it’s important to keep this in mind!

    Bolding applied is my own.

    If you need to patch often it is worthwhile looking into cargo-override which automates overriding crates.