- Feature Name: N/A
- Start Date: 2015-07-10
- RFC PR: rust-lang/rfcs#1200
- Rust Issue: N/A
Add a new subcommand to Cargo,
install, which will install
packages onto the local system in a Cargo-specific directory.
There has almost always been a desire to be able to install Cargo
packages locally, but it's been somewhat unclear over time what the precise
meaning of this is. Now that we have crates.io and lots of experience with
Cargo, however, the niche that
cargo install would fill is much clearer.
Fundamentally, however, Cargo is a ubiquitous tool among the Rust community and
cargo install would facilitate sharing Rust code among its
developers. Simple tasks like installing a new cargo subcommand, installing an
editor plugin, etc, would be just a
cargo install away. Cargo can manage
dependencies and versions itself to make the process as seamless as possible.
Put another way, enabling easily sharing code is one of Cargo's fundamental design goals, and expanding into binaries is simply an extension of Cargo's core functionality.
The following new subcommand will be added to Cargo:
Install a crate onto the local system Installing new crates: cargo install [options] cargo install [options] [-p CRATE | --package CRATE] [--vers VERS] cargo install [options] --git URL [--branch BRANCH | --tag TAG | --rev SHA] cargo install [options] --path PATH Managing installed crates: cargo install [options] --list Options: -h, --help Print this message -j N, --jobs N The number of jobs to run in parallel --features FEATURES Space-separated list of features to activate --no-default-features Do not build the `default` feature --debug Build in debug mode instead of release mode --bin NAME Only install the binary NAME --example EXAMPLE Install the example EXAMPLE instead of binaries -p, --package CRATE Install this crate from crates.io or select the package in a repository/path to install. -v, --verbose Use verbose output --root Directory to install packages into This command manages Cargo's local set of install binary crates. Only packages which have [[bin]] targets can be installed, and all binaries are installed into `$HOME/.cargo/bin` by default (or `$CARGO_HOME/bin` if you change the home directory). There are multiple methods of installing a new crate onto the system. The `cargo install` command with no arguments will install the current crate (as specifed by the current directory). Otherwise the `-p`, `--package`, `--git`, and `--path` options all specify the source from which a crate is being installed. The `-p` and `--package` options will download crates from crates.io. Crates from crates.io can optionally specify the version they wish to install via the `--vers` flags, and similarly packages from git repositories can optionally specify the branch, tag, or revision that should be installed. If a crate has multiple binaries, the `--bin` argument can selectively install only one of them, and if you'd rather install examples the `--example` argument can be used as well. The `--list` option will list all installed packages (and their versions).
Cargo attempts to be as flexible as possible in terms of installing crates from various locations and specifying what should be installed. All binaries will be stored in a cargo-local directory, and more details on where exactly this is located can be found below.
Cargo will not attempt to install binaries or crates into system directories
/usr) as that responsibility is intended for system package managers.
To use installed crates one just needs to add the binary path to their
environment variable. This will be recommended when
cargo install is run if
PATH does not already look like it's configured.
cargo install command will be able to install crates from any source that
Cargo already understands. For example it will start off being able to install
from crates.io, git repositories, and local paths. Like with normal
dependencies, downloads from crates.io can specify a version, git repositories
can specify branches, tags, or revisions.
Sources with multiple crates
Sources like git repositories and paths can have multiple crates inside them, and Cargo needs a way to figure out which one is being installed. If there is more than one crate in a repo (or path), then Cargo will apply the following heuristics to select a crate, in order:
- If the
-pargument is specified, use that crate.
- If only one crate has binaries, use that crate.
- If only one crate has examples, use that crate.
- Print an error suggesting the
Multiple binaries in a crate
Once a crate has been selected, Cargo will by default build all binaries and
install them. This behavior can be modified with the
flags to configure what's installed on the local system.
Building a Binary
cargo install command has some standard build options found on
cargo build and friends, but a key difference is that
--release is the default for
installed binaries so a
--debug flag is present to switch this back to
debug-mode. Otherwise the
--features flag can be specified to activate various
features of the crate being installed.
--target option is omitted as
cargo install is not intended for creating
cross-compiled binaries to ship to other platforms.
Cargo will not namespace the installation directory for crates, so conflicts may
arise in terms of binary names. For example if crates A and B both provide a
foo they cannot be both installed at once. Cargo will reject
these situations and recommend that a binary is selected via
--bin or the
conflicting crate is uninstalled.
Placing output artifacts
cargo install command can be customized where it puts its output artifacts
to install packages in a custom location. The root directory of the installation
will be determined in a hierarchical fashion, choosing the first of the
following that is specified:
--rootargument on the command line.
- The environment variable
- The value of
$CARGO_HOME(also determined in an independent and hierarchical fashion).
Once the root directory is found, Cargo will place all binaries in the
$INSTALL_ROOT/bin folder. Cargo will also reserve the right to retain some
metadata in this folder in order to keep track of what's installed and what
binaries belong to which package.
If Cargo gives access to installing packages, it should surely provide the
ability to manage what's installed! The first part of this is just discovering
what's installed, and this is provided via
cargo install --list.
To remove an installed crate, another subcommand will be added to Cargo:
Remove a locally installed crate Usage: cargo uninstall [options] SPEC Options: -h, --help Print this message --bin NAME Only uninstall the binary NAME --example EXAMPLE Only uninstall the example EXAMPLE -v, --verbose Use verbose output The argument SPEC is a package id specification (see `cargo help pkgid`) to specify which crate should be uninstalled. By default all binaries are uninstalled for a crate but the `--bin` and `--example` flags can be used to only uninstall particular binaries.
Cargo won't remove the source for uninstalled crates, just the binaries that were installed by Cargo itself.
Cargo will not currently attempt to manage anything other than a binary artifact
cargo build. For example the following items will not be available to
- Dynamic native libraries built as part of
- Native assets such as images not included in the binary itself.
- The source code is not guaranteed to exist, and the binary doesn't know where the source code is.
Additionally, Cargo will not immediately provide the ability to configure the installation stage of a package. There is often a desire for a "pre-install script" which runs various house-cleaning tasks. This is left as a future extension to Cargo.
Beyond the standard "this is more surface area" and "this may want to aggressively include more features initially" concerns there are no known drawbacks at this time.
System Package Managers
The primary alternative to putting effort behind
cargo install is to instead
put effort behind system-specific package managers. For example the line between
a system package manager and
cargo install is a little blurry, and the
"official" way to distribute a package should in theory be through a system
package manager. This also has the upside of benefiting those outside the Rust
community as you don't have to have Cargo installed to manage a program. This
approach is not without its downsides, however:
- There are many system package managers, and it's unclear how much effort it would be for Cargo to support building packages for all of them.
- Actually preparing a package for being packaged in a system package manager can be quite onerous and is often associated with a high amount of overhead.
- Even once a system package is created, it must be added to an online repository in one form or another which is often different for each distribution.
All in all, even if Cargo invested effort in facilitating creation of system
packages, the threshold for distribution a Rust program is still too high.
If everything went according to plan it's just unfortunately inherently complex
to only distribute packages through a system package manager because of the
various requirements and how diverse they are. The
cargo install command
provides a cross-platform, easy-to-use, if Rust-specific interface to installing
It is expected that all major Rust projects will still invest effort into
distribution through standard package managers, and Cargo will certainly have
room to help out with this, but it doesn't obsolete the need for
Another possibility for
cargo install is to not only be able to install
binaries, but also libraries. The meaning of this however, is pretty nebulous
and it's not clear that it's worthwhile. For example all Cargo builds will not
have access to these libraries (as Cargo retains control over dependencies). It
may mean that normal invocations of
rustc have access to these libraries (e.g.
for small one-off scripts), but it's not clear that this is worthwhile enough to
support installing libraries yet.
Another possible interpretation of installing libraries is that a developer is
informing Cargo that the library should be available in a pre-compiled form. If
any compile ends up using the library, then it can use the precompiled form
instead of recompiling it. This job, however, seems best left to
as it will automatically handle when the compiler version changes, for example.
It may also be more appropriate to add the caching layer at the
layer instead of