Cargo is the package manager for Rust. It is used to create new projects, manage dependencies, compile code, and publish packages. Cargo uses the Cargo.toml file to define metadata and dependencies, and Cargo.lock to lock dependency versions. Dependencies can come from Crates.io, Git repositories, or local paths. Build scripts allow generating code during compilation. Cargo can publish packages to Crates.io and supports workspaces, environment variables, custom commands, and unstable features for nightly builds.
4. @antweiss@antweiss
The toml and the lock
Cargo.toml: (AKA The Manifest)
[package]
name = "some-app"
version = "0.1.0"
authors = ["Anton Weiss <anton@otomato.link>"]
[dependencies]
tiny_http = "0.6.0"
redis = "0.9.0"
6. @antweiss@antweiss
Depends On...
● Crates from crates.io
[dependencies]
chashmap = "2.2.0"
● Git repos
[dependencies]
evmap = ( git = https://github.com/jonhoo/rust-evmap.git }
● Files in subdirectories of your project
[dependencies]
hello_utils = { path = "hello_utils" }
7. @antweiss@antweiss
Versions of Truth
Cargo.toml:
[dependencies]
clap = "2.20.0"
>cargo build
Updating crates.io index
...
Compiling clap v2.32.0
To ensure specific version -
use:
mylib = "=0.2.3"
Maximal Version
Resolution = At the time
the lockfile is generated
- the latest available
version is used.
8. @antweiss@antweiss
Versions of Truth : Caret
An update is allowed if the new version number does not
modify the left-most non-zero digit in the major, minor,
patch grouping:
[dependencies]
time = "^0.20.0"
Examples:
^1.2.3 := >=1.2.3 <2.0.0
^1.2 := >=1.2.0 <2.0.0
^1 := >=1.0.0 <2.0.0
^0.2.3 := >=0.2.3 <0.3.0
^0.2 := >= 0.2.0 < 0.3.0
^0.0.3 := >=0.0.3 <0.0.4
^0.0 := >=0.0.0 <0.1.0
^0 := >=0.0.0 <1.0.0
9. @antweiss@antweiss
Versions of Truth : Tilde
Specify a minimal version with some ability to update:
[dependencies]
clap = "~2.3.0"
Examples:
~1.2.3 := >=1.2.3 <1.3.0
~1.2 := >=1.2.0 <1.3.0
~1 := >=1.0.0 <2.0.0
10. @antweiss@antweiss
Versions of Truth : Wildcard and Inequality
Wildcard - allow for any version where the wildcard is.
Examples:
* := >=0.0.0
1.* := >=1.0.0 <2.0.0
1.2.* := >=1.2.0 <1.3.0
In/equality - allow manually specifying a version range or
an exact version.
Examples:
>= 1.2.0
> 1
< 2
= 1.2.3
12. @antweiss@antweiss
Versions of Truth : Git
[dependencies]
rand = { git = "https://github.com/rust-lang-nursery/rand" }
= Use the latest commit on ’master’ in the linked repo
Or - specify branch, tag or commit to use:
mylib = { git = "https://mylibrepo" branch = "testing" }
mylib = { git = "https://mylibrepo" tag = "v0.12" }
mylib = { git = "https://mylibrepo" rev = "ede4591" }
13. @antweiss@antweiss
Versions of Truth : Path dependencies
> cargo new mybin
> cd mybin
# inside of mybin:
> cargo new --lib mylib
In Cargo.toml:
[dependencies]
mylib = { path = "mylib" }
Crates with path dependencies are not permitted on
crates.io. We’d need to publish a version of mylib to
crates.io and specify its version like this:
mylib = { path = "mylib" , version = "0.1.0" }
15. @antweiss@antweiss
Multi-crate projects
a [workspace] is a set of crates that all share the same Cargo.lock
and output directory
[package]
name = "wsbin"
version = "0.1.0"
authors = ["Anton Weiss <anton@otomato.link>"]
[workspace]
members = ["wslib", "wsbin2"]
cargo build --all
16. @antweiss@antweiss
Configiring Your Cargo:
● ./.cargo/config
● ../parent/.cargo/config
● $HOME/.cargo/config
Some values:
[cargo-new]
name = "Ant Weiss"
email = "anton@otomato.link"
# By default `cargo new` will initialize a new Git repository.
vcs = "none"
[build]
jobs = 1 # number of parallel jobs, defaults to # of CPUs
rustc = "rustc" # the rust compiler tool
17. @antweiss@antweiss
Environment Variables
● CARGO - Path to the cargo binary performing the build.
● CARGO_MANIFEST_DIR - The directory containing the manifest of your
package.
● CARGO_PKG_VERSION - The full version of your package.
● CARGO_PKG_VERSION_MAJOR - The major version of your package.
● CARGO_PKG_VERSION_MINOR - The minor version of your package.
● CARGO_PKG_VERSION_PATCH - The patch version of your package.
● CARGO_PKG_VERSION_PRE - The pre-release version of your package.
● CARGO_PKG_AUTHORS - Colon separated list of authors from the manifest.
● CARGO_PKG_NAME - The name of your package.
● CARGO_PKG_DESCRIPTION - The description of your package.
● CARGO_PKG_HOMEPAGE - The home page of your package.
● OUT_DIR - If the package has a build script - the folder where it should
place its output.
let app = env!("CARGO_PKG_NAME");
18. @antweiss@antweiss
Build scripts
● Use Cases:
○ Building a bundled C library.
○ Finding a C library on the host system.
○ Generating a Rust module from a specification.
○ Performing any platform-specific configuration needed for the crate.
[package]
# ...
build = "build.rs" #the default
[build-dependencies]
protobuf-codegen-pure = "2.2.0"
20. @antweiss@antweiss
Publishing to Crates.io
Register to Crates.io : log in with your Github account. Go
to ‘Account Settings’ to get your API token.
Log in :
$ cargo login <your_API_token>
Package the crate:
$ cargo package
Publish the crate!:
$ cargo publish
[package]
# ...
exclude = [
"public/assets/*",
"videos/*",
]
21. @antweiss@antweiss
Integrating with the World
CI/CD Tools, IDEs, etc…
$ cargo metadata
Outputs project structure and dependencies information in JSON
$ cargo build --message-format json
Outputs:
● compiler errors and warnings,
● produced artifacts,
● results of the build scripts (for example, native dependencies)
22. @antweiss@antweiss
Custom subcommands
$ cargo my_command == ${PATH}/cargo-my_command
may use the $CARGO environment variable to call back to
Cargo
The list of known cargo subcommands.
25. @antweiss@antweiss
Unstable Features
cargo -Z help
Available unstable (nightly-only) flags:
-Z avoid-dev-deps -- Avoid installing dev-dependencies if possible
-Z minimal-versions -- Install minimal dependency versions instead of
maximum
-Z no-index-update -- Do not update the registry, avoids a network
request for benchmarking
-Z offline -- Offline mode that does not perform network requests
-Z unstable-options -- Allow the usage of unstable options such as
--registry
-Z config-profile -- Read profiles from .cargo/config files
Run with 'cargo -Z [FLAG] [SUBCOMMAND]'