Follow

Follow
Cargo - Commands

Photo by frank mckenna on Unsplash

Cargo - Commands

More about Cargo

Shreyas K S's photo
Shreyas K S
·Sep 24, 2022·

5 min read

Play this article

Cargo is the package manager that aid in downloading and compiling packages. Likewise helps in making packages distributable.

Cargo Build Commands

Compile Packages

cargo build - Compile the current package.

cargo build [OPTIONS]

OPTIONS

  1. Package Selection: When no package selection is given, the package selected depends on the selected manifest file which depends on the current working directory.

    --package specific package -> Build only the specified packages.

    --workspace -> Build all members in the workspace.

    --exclude -> Exclude specified packages for building.

  2. Target Selection: Cargo builds all the binary targets when no target option is specified.

    --lib -> Build the package's library.

    --bin -> Build the specified binary.

    --bins -> Build all binary targets.

    --example -> Build the specified example.

  3. Feature Selection: These feature flags aid in controlling which features are enabled. If nothing is specified, cargo selects default features for the selected package.

    --features feature -> Space or comma-separated list of features to activate. Features of workspace members may be enabled with package-name/feature-name syntax. This flag may be specified multiple times, which enables all specified features.

    --all-features -> Activate all available features of all selected packages.

    --no-default-features -> Do not activate the default feature of the selected packages.

  4. Output Selection: To specify cargo to build the output.

    --target-dir -> Directory for all generated artifacts and intermediate files.

    --out-dir -> Copy final artifacts to the directory mentioned. This option is unstable and available only on the nightly channel and requires the -Z unstable-options flag to enable.

Run Packages

cargo run - Run the current package. Run a binary or example of the local package.

All the arguments following the two dashes (--) are passed to the binary to run. If you're passing arguments to both Cargo and the binary, the ones after -- go to the binary, and the ones before go to Cargo.

cargo run [OPTIONS] [--args]

Test Packages

cargo test - Execute unit and Integration tests of a package.

Compile and execute unit, integration, and documentation tests.

The test filtering argument TEST NAME and all the arguments following the two dashes (--) are passed to the test binaries and thus to libtest (rustc's built-in unit-test and micro-benchmarking framework). If you're passing arguments to both Cargo and the binary, the ones after -- go to the binary, and the ones before go to Cargo. For details about libtest's arguments see the output of cargo test -- --help and check out the rustc book's chapter on how tests work.

cargo test [OPTIONS] [testname] [-- test-options]

Documentation For Packages

cargo doc - This command builds a package's documentation. Build the documentation for the local package and all dependencies. The output is placed in target/doc in rustdoc's usual format.

cargo doc [OPTIONS]
  • Documentation Options:

    --open -> Open the docs in a browser after building them. This will use your default browser unless you define another one in the BROWSER environment variable or use the doc.browser configuration option.

    --no-deps -> Do not build documentation for dependencies.

    --document-private-items -> Include non-public items in the documentation. This will be enabled by default if documenting a binary target.

Cargo Package Commands

Init

cargo init Creates a new cargo package in an existing directory.

cargo init [OPTIONS][path]

This command will create a new Cargo manifest in the current directory. Give a path as an argument to create in the given directory.

Install

cargo install - This command aid in building and installing a rust binary.

cargo install [OPTIONS] crate[@version]...
cargo install [OPTIONS] --path path
cargo install [OPTIONS] --git URL [crate...]
cargo install [OPTIONS] --list

This command manages Cargo's local set of installed binary crates. Only packages which have executable [[bin]] or [[example]] targets can be installed, and all executables are installed into the installation root's bin folder.

The installation root is chosen, in order of precedence:

  • --root option
  • CARGO_INSTALL_ROOT environment variable
  • install.root Cargo config value
  • CARGO_HOME environment variable
  • $HOME/.cargo

New

cargo new - Creates a new Cargo package.

cargo new [OPTONS] path

This command will create a new Cargo package in the given directory. This includes a simple template with a Cargo.toml manifest, a sample source file, and a VCS ignore file.

Cargo Publishing Commands

Login

cargo login - This allows the user to login to crates.io

cargo login [OPTIONS] [token]

This command will save the API token to disk so that commands that require authentication will be automatically authenticated. The token is saved in $CARGO_HOME/credentials.toml. CARGO_HOME defaults to .cargo in your home directory.

If the token argument is not specified, it will be read from stdin.

The API token for crates.io may be retrieved from crates.io

Take care to keep the token secret, it should not be shared with anyone else.

Publish

cargo publish - Uploads a package to the registry (crates.io).

cargo publish [OPTIONS]

This command will create a distributable, compressed .crate file with the source code of the package in the current directory and upload it to a registry. The default registry is crates.io. This performs the following steps:

  1. Performs a few checks, including -> Checks the package.publish the key in the manifest for restrictions on which registries you are allowed to publish to.
  2. Create a .crate file by following the steps in cargo-package(1).
  3. Upload the crate to the registry. Note that the server will perform additional checks on the crate.

For more details on packaging and publishing follow this link

These are the few cargo commands which are used frequently. To know more about Cargo (The Rust Package Manager) refer to the rust official documentation.

Did you find this article valuable?

Support Shreyas K S by becoming a sponsor. Any amount is appreciated!

Learn more about Hashnode Sponsors
 
Share this