Rust cargo: Difference between revisions
From wikinotes
No edit summary |
|||
(19 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
cargo is rust's build system, | cargo is rust's build system, package manager, test-runner, and lots more.<br> | ||
it's sort of rust's swiss army knife. | |||
= Documentation = | = Documentation = | ||
<blockquote> | <blockquote> | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |||
| book: cargo reference || https://doc.rust-lang.org/cargo/reference/index.html | |||
|- | |||
| <code>Cargo.toml</code> docs || https://doc.rust-lang.org/cargo/reference/manifest.html | |||
|- | |||
| cargo commands || https://doc.rust-lang.org/cargo/commands/index.html | |||
|- | |- | ||
| <code>man cargo</code> || https://man.archlinux.org/man/extra/rust/cargo.1.en | | <code>man cargo</code> || https://man.archlinux.org/man/extra/rust/cargo.1.en | ||
|- | |- | ||
|} | |} | ||
Line 38: | Line 43: | ||
= Usage = | = Usage = | ||
<blockquote> | |||
{| class="wikitable" | |||
|- | |||
| cargo commands || https://doc.rust-lang.org/cargo/commands/index.html | |||
|- | |||
|} | |||
== Project Management == | |||
<blockquote> | <blockquote> | ||
<syntaxhighlight lang="bash"> | <syntaxhighlight lang="bash"> | ||
cargo new my_project # create project | cargo new my_project # create project | ||
# build | |||
cargo build # compile project (for testing) | cargo build # compile project (for testing) | ||
cargo run # compile/run executable | cargo run # compile/run executable | ||
cargo check # check project can build, without building | cargo check # check project can build, without building | ||
cargo build --release # build w/ optimizations (more performant) | |||
cargo test # run tests | |||
# dependencies | |||
cargo update # update all packages | |||
cargo update -p regex # update only 'regex' package | |||
</syntaxhighlight> | |||
</blockquote><!-- Project Management --> | |||
== Publishing Packages == | |||
<blockquote> | |||
In order to publish a crate, you need a <code>crates.io</code> account. | |||
cargo | <syntaxhighlight lang="bash"> | ||
# 1. manually create an account on https://crates.io | |||
# 2. retrieve API key from https://crates.io/me | |||
# 3. register your API key locally | |||
cargo login ${your_api_key} | |||
</syntaxhighlight> | |||
Now you can publish a crate using <code>cargo publish</code>.<br> | |||
you'll need to update the <code>version</code> between each publish. | |||
<syntaxhighlight lang="bash"> | |||
cargo publish # publish crate version | |||
cargo yank --vers 1.1.1 # mark version bad, disallowing new users from requesting this version | |||
</syntaxhighlight> | </syntaxhighlight> | ||
</blockquote><!-- Publishing Packages --> | |||
</blockquote><!-- usage --> | </blockquote><!-- usage --> | ||
= Configuration = | = Project Configuration = | ||
<blockquote> | |||
== Basics == | |||
<blockquote> | <blockquote> | ||
<syntaxhighlight lang="toml"> | <syntaxhighlight lang="toml"> | ||
# ${PROJECT}/Cargo.toml | |||
[package] | [package] | ||
name = "hello_cargo" | name = "hello_cargo" | ||
Line 59: | Line 105: | ||
[dependencies] | [dependencies] | ||
time = "0.1.12" | |||
regex = "0.1.41" | |||
rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" } | |||
</syntaxhighlight> | |||
</blockquote><!-- Basics --> | |||
== Dependencies == | |||
<blockquote> | |||
{| class="wikitable" | |||
|- | |||
| Intro || https://doc.rust-lang.org/cargo/guide/dependencies.html | |||
|- | |||
| Dependencies || https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html | |||
|- | |||
| Overriding Dependencies || https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html | |||
|- | |||
| Optional Dependencies || https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies | |||
|- | |||
|} | |||
=== Add Dependency === | |||
<blockquote> | |||
* To add a dependency, add it to your <code>Cargo.toml</code> under <code>[dependencies]</code>. | |||
* Then run <code>cargo build</code> | |||
<syntaxhighlight lang="toml"> | |||
# ... | |||
[dependencies] | |||
rand = "0.8.5" | |||
</syntaxhighlight> | |||
<syntaxhighlight lang="bash"> | |||
cargo build # fetch packages and compile | |||
</syntaxhighlight> | |||
</blockquote><!-- Add Dependency --> | |||
=== Update Dependency === | |||
<blockquote> | |||
First, update the version-request in your <code>Cargo.toml</code> | |||
<syntaxhighlight lang="toml"> | |||
[dependencies] | |||
rand = "0.9.0" | |||
</syntaxhighlight> | |||
Then cargo build | |||
<syntaxhighlight lang="bash"> | |||
cargo update # ignore cargo.toml | |||
</syntaxhighlight> | |||
</blockquote><!-- Update Dependency --> | |||
=== Version Requests === | |||
<blockquote> | |||
<syntaxhighlight lang="toml"> | |||
# ${PROJECT}/Cargo.toml | |||
[dependencies] | |||
time = "0.1.12" | |||
foo = "^0.8.5" # 0.8.5 <= 0.9 | |||
rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" } | |||
gif = { version = "0.11.1", optional = true } | |||
</syntaxhighlight> | </syntaxhighlight> | ||
* Optional dependencies define features of the same name | |||
</blockquote><!-- Version Requests --> | |||
</blockquote><!-- Dependencies --> | |||
== Features == | |||
<blockquote> | |||
{| class="wikitable" | |||
|- | |||
| features || https://doc.rust-lang.org/cargo/reference/features.html | |||
|- | |||
|} | |||
Features can be defined, and enabled/disabled at build time. | |||
Define features in your <code>Cargo.toml</code> | |||
<syntaxhighlight lang="toml"> | |||
# ${PROJECT}/Cargo.toml | |||
[features] | |||
lua = [] | |||
python = [] | |||
airline = ["python"] | |||
</syntaxhighlight> | |||
<syntaxhighlight lang="rust"> | |||
#[cfg(feature = "python")] | |||
pub mod embed_python; | |||
</syntaxhighlight> | |||
</blockquote><!-- Features --> | |||
== Workspaces == | |||
<blockquote> | |||
{| class="wikitable" | |||
|- | |||
| workspaces || https://doc.rust-lang.org/cargo/reference/workspaces.html | |||
|- | |||
|} | |||
</blockquote><!-- Workspaces --> | |||
</blockquote><!-- Configuration --> | </blockquote><!-- Configuration --> |
Latest revision as of 21:31, 9 February 2023
cargo is rust's build system, package manager, test-runner, and lots more.
it's sort of rust's swiss army knife.
Documentation
book: cargo reference https://doc.rust-lang.org/cargo/reference/index.html Cargo.toml
docshttps://doc.rust-lang.org/cargo/reference/manifest.html cargo commands https://doc.rust-lang.org/cargo/commands/index.html man cargo
https://man.archlinux.org/man/extra/rust/cargo.1.en
Global Locations
~/.cargo/bin/*
cargo installed executables ~/.config/registry/*
cached cargo registry indexes ~/.cargo/config.toml
global config ~/.config/credentials.toml
cargo registry credentials
Project Locations
${PROJECT}/Cargo.toml
project config ${PROJECT}/Cargo.lock
frozen package versions
Usage
cargo commands https://doc.rust-lang.org/cargo/commands/index.html Project Management
cargo new my_project # create project # build cargo build # compile project (for testing) cargo run # compile/run executable cargo check # check project can build, without building cargo build --release # build w/ optimizations (more performant) cargo test # run tests # dependencies cargo update # update all packages cargo update -p regex # update only 'regex' packagePublishing Packages
In order to publish a crate, you need a
crates.io
account.# 1. manually create an account on https://crates.io # 2. retrieve API key from https://crates.io/me # 3. register your API key locally cargo login ${your_api_key}Now you can publish a crate using
cargo publish
.
you'll need to update theversion
between each publish.cargo publish # publish crate version cargo yank --vers 1.1.1 # mark version bad, disallowing new users from requesting this version
Project Configuration
Basics
# ${PROJECT}/Cargo.toml [package] name = "hello_cargo" version = "0.1.0" authors = ["Your Name <you@example.com>"] edition = "2018" [dependencies] time = "0.1.12" regex = "0.1.41" rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }Dependencies
Intro https://doc.rust-lang.org/cargo/guide/dependencies.html Dependencies https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html Overriding Dependencies https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html Optional Dependencies https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies Add Dependency
- To add a dependency, add it to your
Cargo.toml
under[dependencies]
.- Then run
cargo build
# ... [dependencies] rand = "0.8.5"cargo build # fetch packages and compileUpdate Dependency
First, update the version-request in your
Cargo.toml
[dependencies] rand = "0.9.0"Then cargo build
cargo update # ignore cargo.tomlVersion Requests
# ${PROJECT}/Cargo.toml [dependencies] time = "0.1.12" foo = "^0.8.5" # 0.8.5 <= 0.9 rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" } gif = { version = "0.11.1", optional = true }
- Optional dependencies define features of the same name
Features
features https://doc.rust-lang.org/cargo/reference/features.html Features can be defined, and enabled/disabled at build time.
Define features in your
Cargo.toml
# ${PROJECT}/Cargo.toml [features] lua = [] python = [] airline = ["python"]#[cfg(feature = "python")] pub mod embed_python;Workspaces
workspaces https://doc.rust-lang.org/cargo/reference/workspaces.html