jmarya/knowledge
jmarya/knowledge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

add cargo

Browse source
This commit is contained in:
JMARyA 2023-12-22 23:14:44 +01:00
parent 0708110273
commit 9119289dc0
Signed by: jmarya
GPG key ID: 901B2ADDF27C2263
1 changed files with 326 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

326
technology/applications/development/cargo.md Normal file
View file

@ -0,0 +1,326 @@
---
obj: application
---
# cargo
[Cargo](https://doc.rust-lang.org/cargo/) is the official package manager for the [Rust](../../programming/languages/Rust.md) programming language. It serves as a build system, package manager, and dependency manager for [Rust](../../programming/languages/Rust.md) projects. Cargo makes it easy to manage, build, and distribute [Rust](../../programming/languages/Rust.md) projects, handling tasks such as compiling code, managing dependencies, and running tests.
## `cargo add`
Add dependencies to a `Cargo.toml` manifest file
### Options
| Option | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--no-default-features` | Disable the default features |
| `--default-features` | Re-enable the default features |
| `-F, --features <FEATURES>` | Space or comma separated list of features to activate |
| `--optional` | Mark the dependency as optional. The package name will be exposed as feature of your crate. |
| `--no-optional` | Mark the dependency as required. The package will be removed from your features. |
| `--rename <NAME>` | Rename the dependency |
| `--dry-run` | Don't actually write the manifest |
| `-q, --quiet` | Do not print cargo log messages |
| `-v, --verbose...` | Use verbose output (-vv very verbose/build.rs output) |
| `--manifest-path <PATH>` | Path to `Cargo.toml` |
| `--path <PATH>` | Filesystem path to local crate to add |
| `--git <URI>` | [Git](../../dev/Git.md) repository location |
| `--branch <BRANCH>` | [Git](../../dev/Git.md) branch to download the crate from |
| `--tag <TAG>` | [Git](../../dev/Git.md) tag to download the crate from |
| `--rev <REV>` | [Git](../../dev/Git.md) reference to download the crate from |
| `--registry <NAME>` | Package registry for this dependency |
| `--dev` | Add as development dependency. Dev-dependencies are not used when compiling a package for building, but are used for compiling tests, examples, and benchmarks. These dependencies are not propagated to other packages which depend on this package. |
| `--build` | Add as build dependency. Build-dependencies are the only dependencies available for use by build scripts (`build.rs` files). |
| `--target <TARGET>` | Add as dependency to the given target platform |
## `cargo build`
Compile a local package and all of its dependencies
### Options
| Option | Description |
| --------------------------- | ----------------------------------------------------- |
| `--lib` | Build only this package's library |
| `--bins` | Build all binaries |
| `--bin [<NAME>]` | Build only the specified binary |
| `--examples` | Build all examples |
| `--example [<NAME>]` | Build only the specified example |
| `--tests` | Build all tests |
| `--test [<NAME>]` | Build only the specified test target |
| `--all-targets` | Build all targets |
| `-F, --features <FEATURES>` | Space or comma separated list of features to activate |
| `--all-features` | Activate all available features |
| `--no-default-features` | Do not activate the `default` feature |
| `-r, --release` | Build artifacts in release mode, with optimizations |
| `-j, --jobs <N>` | Number of parallel jobs, defaults to # of CPUs. |
## `cargo check`
Check a local package and all of its dependencies for errors
## `cargo clean`
Remove artifacts that cargo has generated in the past
Usage: `cargo clean`
## `cargo clippy`
Checks a package to catch common mistakes and improve your [Rust](../../programming/languages/Rust.md) code.
### Options
| Option | Description |
| ---------------- | --------------------------------------------------------------------------------------- |
| `--no-deps` | Run Clippy only on the given crate, without linting the dependencies |
| `--fix` | Automatically apply lint suggestions. This flag implies `--no-deps` and `--all-targets` |
| `--explain LINT` | Print the documentation for a given lint |
To allow or deny a lint from the command line you can use `cargo clippy --` with:
| Option | Description |
| ----------------- | ------------------ |
| `-W --warn OPT` | Set lint warnings |
| `-A --allow OPT` | Set lint allowed |
| `-D --deny OPT` | Set lint denied |
| `-F --forbid OPT` | Set lint forbidden |
## `cargo doc`
Build a package's documentation
### Options
| Option | Description |
| -------------------------- | ----------------------------------------------- |
| `--open` | Opens the docs in a browser after the operation |
| `--no-deps` | Don't build documentation for dependencies |
| `--document-private-items` | Document private items |
## `cargo fetch`
Fetch dependencies of a package from the network
## `cargo fmt`
Formats all bin and lib files of the current crate using rustfmt.
Usage: `cargo fmt [--check]`
## `cargo init`
Create a new cargo package in an existing directory
### Options
| Option | Description |
| ------------------ | --------------------------------------------------------------------------- |
| `--bin` | Use a binary (application) template \[default] |
| `--lib` | Use a library template |
| `--edition <YEAR>` | Edition to set for the crate generated \[possible values: 2015, 2018, 2021] |
| `--name <NAME>` | Set the resulting package name, defaults to the directory name |
## `cargo install`
Install a [Rust](../../programming/languages/Rust.md) binary. Default location is `$HOME/.cargo/bin`
### Options
| Option | Description |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| `--version <VERSION>` | Specify a version to install |
| `--index <INDEX>` | Registry index to install from |
| `--registry <REGISTRY>` | Registry to use |
| `--git <URL>` | [Git](../../dev/Git.md) [URL](../../internet/URL.md) to install the specified crate from |
| `--branch <BRANCH>` | Branch to use when installing from [git](../../dev/Git.md) |
| `--tag <TAG>` | Tag to use when installing from [git](../../dev/Git.md) |
| `--rev <SHA>` | Specific commit to use when installing from [git](../../dev/Git.md) |
| `--path <PATH>` | Filesystem path to local crate to install |
| `--root <DIR>` | Directory to install packages into |
| `-f, --force` | Force overwriting existing crates or binaries |
| `--no-track` | Do not save tracking information |
| `--list` | list all installed packages and their versions |
| `-q, --quiet` | Do not print cargo log messages |
| `-v, --verbose...` | Use verbose output (-vv very verbose/build.rs output) |
| `--bin [<NAME>]` | Install only the specified binary |
| `--bins` | Install all binaries |
| `--example [<NAME>]` | Install only the specified example |
| `--examples` | Install all examples |
## `cargo login`
Log in to a registry.
Usage: `cargo login --registry registry <token>`
## `cargo logout`
Remove an API token from the registry locally.
Usage: `cargo logout --registry reg`
## `cargo new`
Create a new cargo package
### Options
| Option | Description |
| ------------------ | --------------------------------------------------------------------------- |
| `--bin` | Use a binary (application) template \[default] |
| `--lib` | Use a library template |
| `--edition <YEAR>` | Edition to set for the crate generated \[possible values: 2015, 2018, 2021] |
| `--name <NAME>` | Set the resulting package name, defaults to the directory name |
## `cargo package`
Assemble the local package into a distributable tarball
### Options
| Option | Description |
| ------------------ | ----------------------------------------------------- |
| `-l, --list` | Print files included in a package without making one |
| `--no-verify` | Don't verify the contents by building them |
| `--no-metadata` | Ignore warnings about a lack of human-usable metadata |
| `--allow-dirty` | Allow dirty working directories to be packaged |
| `-q, --quiet` | Do not print cargo log messages |
| `-v, --verbose...` | Use verbose output (-vv very verbose/build.rs output) |
## `cargo publish`
Upload a package to the registry
### Options
| Option | Description |
| ----------------------- | -------------------------------------------------------------------- |
| `--dry-run` | Perform all checks without uploading |
| `--index <INDEX>` | Registry index [URL](../../internet/URL.md) to upload the package to |
| `--registry <REGISTRY>` | Registry to publish to |
| `--token <TOKEN>` | Token to use when uploading |
| `--no-verify` | Don't verify the contents by building them |
| `--allow-dirty` | Allow dirty working directories to be packaged |
| `-q, --quiet` | Do not print cargo log messages |
| `-v, --verbose...` | Use verbose output (-vv very verbose/build.rs output) |
## `cargo metadata`
Print a [JSON](../../files/JSON.md) representation of a `Cargo.toml` manifest.
Usage: `cargo metadata --no-deps`
## `cargo remove`
Remove dependencies from a `Cargo.toml` manifest file
### Options
| Option | Description |
| ------------------- | --------------------------------------------------- |
| `--dry-run` | Don't actually write the manifest |
| `--dev` | Remove as development dependency |
| `--build` | Remove as build dependency |
| `--target <TARGET>` | Remove as dependency from the given target platform |
## `cargo run`
Run a binary or example of the local package
### Options
| Option | Description |
| --------------------------- | ----------------------------------------------------- |
| `--bin <NAME>` | Name of the bin target to run |
| `--example <NAME>` | Name of the example target to run |
| `-F, --features <FEATURES>` | Space or comma separated list of features to activate |
| `--all-features` | Activate all available features |
| `--no-default-features` | Do not activate the `default` feature |
| `-j, --jobs <N>` | Number of parallel jobs, defaults to # of CPUs |
| `-r, --release` | Build artifacts in release mode, with optimizations |
## `cargo search`
Search packages in registry.
Usage: `cargo search [--registry registry] [--limit limit] package`
## `cargo test`
Execute all unit and integration tests and build examples of a local package
## `cargo tree`
Display a tree visualization of a dependency graph
## `cargo uninstall`
Remove a [Rust](../../programming/languages/Rust.md) binary
## `cargo update`
Update dependencies as recorded in the local lock file
Usage: `cargo update [--dry-run]`
## Manifest
The `Cargo.toml` file for each package is called its manifest. It is written in the [TOML](../../files/TOML.md) format. It contains metadata that is needed to compile the package.
Every manifest file consists of the following sections:
- [`cargo-features`](https://doc.rust-lang.org/cargo/reference/unstable.html) — Unstable, nightly-only features.
- [`[package]`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-package-section) — Defines a package.
- [`name`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field) — The name of the package.
- [`version`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-version-field) — The version of the package.
- [`authors`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-authors-field) — The authors of the package.
- [`edition`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-edition-field) — The [Rust](../../programming/languages/Rust.md) edition.
- [`rust-version`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field) — The minimal supported [Rust](../../programming/languages/Rust.md) version.
- [`description`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-description-field) — A description of the package.
- [`documentation`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-documentation-field) — [URL](../../internet/URL.md) of the package documentation.
- [`readme`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-readme-field) — Path to the package’s README file.
- [`homepage`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-homepage-field) — [URL](../../internet/URL.md) of the package homepage.
- [`repository`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-repository-field) — [URL](../../internet/URL.md) of the package source repository.
- [`license`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields) — The package license.
- [`license-file`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields) — Path to the text of the license.
- [`keywords`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-keywords-field) — Keywords for the package.
- [`categories`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-categories-field) — Categories of the package.
- [`workspace`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-workspace-field) — Path to the workspace for the package.
- [`build`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-build-field) — Path to the package build script.
- [`links`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-links-field) — Name of the native library the package links with.
- [`exclude`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) — Files to exclude when publishing.
- [`include`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) — Files to include when publishing.
- [`publish`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-publish-field) — Can be used to prevent publishing the package.
- [`metadata`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table) — Extra settings for external tools.
- [`default-run`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-default-run-field) — The default binary to run by [`cargo run`](https://doc.rust-lang.org/cargo/commands/cargo-run.html).
- [`autobins`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#target-auto-discovery) — Disables binary auto discovery.
- [`autoexamples`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#target-auto-discovery) — Disables example auto discovery.
- [`autotests`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#target-auto-discovery) — Disables test auto discovery.
- [`autobenches`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#target-auto-discovery) — Disables bench auto discovery.
- [`resolver`](https://doc.rust-lang.org/cargo/reference/resolver.html#resolver-versions) — Sets the dependency resolver to use.
- Target tables: (see [configuration](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#configuring-a-target) for settings)
- [`[lib]`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#library) — Library target settings.
- [`[[bin]]`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#binaries) — Binary target settings.
- [`[[example]]`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#examples) — Example target settings.
- [`[[test]]`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#tests) — Test target settings.
- [`[[bench]]`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#benchmarks) — Benchmark target settings.
- Dependency tables:
- [`[dependencies]`](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) — Package library dependencies.
- [`[dev-dependencies]`](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies) — Dependencies for examples, tests, and benchmarks.
- [`[build-dependencies]`](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies) — Dependencies for build scripts.
- [`[target]`](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies) — Platform-specific dependencies.
- [`[badges]`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section) — Badges to display on a registry.
- [`[features]`](https://doc.rust-lang.org/cargo/reference/features.html) — Conditional compilation features.
- [`[lints]`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-lints-section) — Configure linters for this package.
- [`[patch]`](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#the-patch-section) — Override dependencies.
- [`[profile]`](https://doc.rust-lang.org/cargo/reference/profiles.html) — Compiler settings and optimizations.
- [`[workspace]`](https://doc.rust-lang.org/cargo/reference/workspaces.html) — The workspace definition.
## Build Scripts
Some packages need to compile third-party non-[Rust](../../programming/languages/Rust.md) code, for example C libraries. Other packages need to link to C libraries which can either be located on the system or possibly need to be built from source. Others still need facilities for functionality such as code generation before building (think parser generators).
Cargo does not aim to replace other tools that are well-optimized for these tasks, but it does integrate with them with custom build scripts. Placing a file named `build.rs` in the root of a package will cause Cargo to compile that script and execute it just before building the package.
```rust
// Example custom build script.
fn main() {
// Tell Cargo that if the given file changes, to rerun this build script.
println!("cargo:rerun-if-changed=src/hello.c");
// Use the `cc` crate to build a C file and statically link it.
cc::Build::new()
.file("src/hello.c")
.compile("hello");
}
```
## Environment Variables
When the build script is run, there are a number of inputs to the build script, all passed in the form of [environment variables](../../linux/Environment%20Variables.md).
Cargo exposes these [environment variables](../../linux/Environment%20Variables.md) to your crate when it is compiled. Note that this applies for running binaries with `cargo run` and `cargo test` as well. To get the value of any of these variables in a [Rust](../../programming/languages/Rust.md) program, do this:
```rust
let version = env!("CARGO_PKG_VERSION");
```
Exposed 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 of your package.
- `CARGO_PKG_NAME` — The name of your package.
- `CARGO_PKG_DESCRIPTION` — The description from the manifest of your package.
- `CARGO_PKG_HOMEPAGE` — The home page from the manifest of your package.
- `CARGO_PKG_REPOSITORY` — The repository from the manifest of your package.
- `CARGO_PKG_LICENSE` — The license from the manifest of your package.
- `CARGO_PKG_LICENSE_FILE` — The license file from the manifest of your package.
- `CARGO_PKG_RUST_VERSION` — The [Rust](../../programming/languages/Rust.md) version from the manifest of your package. Note that this is the minimum [Rust](../../programming/languages/Rust.md) version supported by the package, not the current [Rust](../../programming/languages/Rust.md) version.
- `CARGO_PKG_README` — Path to the README file of your package.
- `CARGO_CRATE_NAME` — The name of the crate that is currently being compiled. It is the name of the Cargo target with `-` converted to `_`, such as the name of the library, binary, example, integration test, or benchmark.
- `CARGO_BIN_NAME` — The name of the binary that is currently being compiled. Only set for binaries or binary examples. This name does not include any file extension, such as `.exe`.
- `OUT_DIR` — If the package has a build script, this is set to the folder where the build script should place its output.
- `CARGO_BIN_EXE_<name>` — The absolute path to a binary target’s executable. This is only set when building an integration test or benchmark. This may be used with the `env` macro to find the executable to run for testing purposes. The `<name>` is the name of the binary target, exactly as-is. For example, `CARGO_BIN_EXE_my-program` for a binary named `my-program`. Binaries are automatically built when the test is built, unless the binary has required features that are not enabled.
- `CARGO_PRIMARY_PACKAGE` — This environment variable will be set if the package being built is primary. Primary packages are the ones the user selected on the command-line, either with `-p` flags or the defaults based on the current directory and the default workspace members. This environment variable will not be set when building dependencies. This is only set when compiling the package (not when running binaries or tests).
- `CARGO_TARGET_TMPDIR` — Only set when building integration test or benchmark code. This is a path to a directory inside the target directory where integration tests or benchmarks are free to put any data needed by the tests/benches. Cargo initially creates this directory but doesn’t manage its content in any way, this is the responsibility of the test code.