How to use the command 'cargo publish' (with examples)

Cargo is a package management tool for the Rust programming language. The cargo publish command is used to upload a package to a registry. Before publishing a package, an authentication token needs to be added using cargo login. This command allows users to perform checks, create a .crate file, and upload it to the registry.

Use case 1: Perform checks, create a .crate file and upload it to the registry

Code:

cargo publish

Motivation: The motivation behind using this example is to publish a package to a registry. By running this command, Cargo will first perform necessary checks such as compiling the package and running tests. If the checks pass, it will create a .crate file and upload it to the registry.

Explanation: cargo publish is the command used to perform these actions. It checks the code for errors, compiles the package, runs tests, and creates a .crate file. Finally, it uploads the .crate file to the registry.

Example output:

$ cargo publish
    Checking package
    Compiling my_package v0.1.0 (...)
    Fetching dependencies
    ...
    Finished release [optimized] target(s) in 0.32s
    Running package tests

    Documenting my_package v0.1.0 (...)
    Uploading my_package v0.1.0 (...)
    Published my_package v0.1.0 (...)

Use case 2: Perform checks, create a .crate file but don’t upload it (equivalent of cargo package)

Code:

cargo publish --dry-run

Motivation: The motivation behind using this example is to simulate the package publication process without actually uploading the package to the registry. It allows users to check if their code is ready for publishing before performing the actual upload.

Explanation: Adding the --dry-run flag to the cargo publish command ensures that the package is not uploaded to the registry. Instead, Cargo performs all the necessary checks, creates a .crate file, and displays the output as if the package was published.

Example output:

$ cargo publish --dry-run
    Checking package
    Compiling my_package v0.1.0 (...)
    Fetching dependencies
    ...
    Finished release [optimized] target(s) in 0.32s
    Running package tests

    Documenting my_package v0.1.0 (...)
    Packaging my_package v0.1.0 (...)
    Verifying my_package v0.1.0 (...)

Use case 3: Specify the name of the registry to use

Code:

cargo publish --registry name

Motivation: The motivation behind using this example is to specify a specific registry to use for publishing the package. By default, Cargo uses the https://crates.io registry. However, there might be cases where users want to publish their packages to a different registry.

Explanation: By providing the --registry flag followed by the name of the desired registry, users can specify which registry to use for publishing their package. Registry names can be defined in the Cargo config. This allows for flexibility in choosing the destination registry.

Example output:

$ cargo publish --registry my_registry
    Checking package
    Compiling my_package v0.1.0 (...)
    Fetching dependencies
    ...
    Finished release [optimized] target(s) in 0.32s
    Running package tests

    Documenting my_package v0.1.0 (...)
    Uploading my_package v0.1.0 (...) to my_registry
    Published my_package v0.1.0 (...).

Conclusion:

The cargo publish command is an essential tool for Rust developers to publish their packages to a registry. By using this command, developers can ensure that their code passes all necessary checks, create a .crate file, and either upload it to the default registry or specify a custom registry. These examples demonstrate the different use cases of the cargo publish command, providing users with flexibility and control over the package publication process.