Note: this project is at an early stage. While all documented functionality is actually implemented, the featureset is still quite limited. It may still be considered good enough for a MVP.
While cargo install is a convenient way to install binaries provided
by crates onto your system, it falls short if the crates need
additional resources to be installed, such man pages, icons, sound
files, etc. Additionally, there seems to be no established convention
in the Rust ecosystem to allow access to resources installed along the
application, regardless of where they are installed.
cargo-parcel is actually an application of the [xtask pattern],
which, when I stumbled upon it gave rise to the idea of
cargo-parcel. While cargo-xtask is "a way to add free-form
automation to a Rust project, ...", cargo-parcel is a specific
implementation of that idea, taking away the "free-form" part, instead
focusing on application installation and distribution, and on defining
a declarative way to describe those.
As a motivating example, let's say you are developing a crate that
provides a frobnitz binary that plays sound samples, and you want to
include some sample sounds with your program. Furthermore, you want to
be a good citizen of the *nix ecosystem and provide man pages that
describe frobnitz in excessive detail. Furthermore, you want to make
it easy for Linux distributions and similar efforts to package
frobnitz for their respective package systems. This means in
practice that you want to be able to meet the following requirements:
frobnitz, along with documentation and other resources
below an arbitrary location provided by the user. On Unix systems
the default locations are conventionally below /usr/local for
system-wide locations, and ~/.local for per-user
installations. The ~/.local directory is a convention described by
the [XDG Base Directory Specification]. The installation target root
directory is usually referred to as the installation prefix.frobnitz,
so it can locate installed resources without the user needing to
specify their location, regardless of the chosen installation
prefix.DESTDIR] in
the autotools world. It is especially useful for distribution
packaging tools, which need to be able to operate without root
privileges, and must not write to the location the built package
will eventually be installed in.cargo-parcel is an attempt to allow binary crate authors easily meet
the requirements described above. It also allows integrating common
tasks, such as building man pages, into the installation
process. Furthermore, it provides a way to create simple binary
distribution archives, which come in handy in case you want to provide
distribution-independent binary packages for your users, or for
deployment to a different system from source.
You can make use of cargo-parcel in your own crate with by adding a
bit of metadata to the Cargo.toml file, specifically the
package.metadata.parcel table, which is described below. As the
metadata format is expected to evolve, there is currently no
cargo-parcel cargo plugin, and you must add some additional
boilerplate to tie your code to a specific version of cargo-parcel,
effectively defining the cargo parcel command in your own crate.
There are two sides to using cargo-parcel; application crate authors
will want to have a look at how to integrate
it into their crate, while users of crates employing cargo-parcel
may be more interested in the CLI guide. The
behavior of cargo-parcel is configured by the
package.metadata.parcel table in Cargo.toml. The available
settings are described the metadata reference.
A short overview over the available commands and their most important options is provided below. For a complete account see the CLI guide or the built-in command-line interface help.
cargo parcel install [--prefix DIR] [--dest-dir DIR]
Install the parcel contents into the given --prefix directory
(~/.local by default), optionally relocating the installation to
the given --dest-dir directory.
cargo parcel uninstall [--prefix DIR] [--dest-dir DIR]
Counteract the actions of an equivalent install commend;
i.e. uninstall the package contents.
cargo parcel bundle [-o FILE] [--prefix DIR] [--root DIR]
Produce a distribution "bundle"; currently TAR archives are supported by calling out to GNU tar.
To understand the goals of cargo-parcel, it is helpful to contrast
it with a generic task runner like [cargo-make]:
cargo-make, you can define arbitrary tasks, while
cargo-parcel defines a few fixed commands focused on application
installation and distribution.cargo-parcel tries to be declarative, describing the "what", not
the how. Other tools should be able to make use of the parcel
metadata, without having to run cargo-parcel, or partially
re-implement it.There are some crates that provide functionality overlapping with
cargo-parcel; after a casual search, I found the following ones. If
you know of others, please file an issue, and I'll add them to the
list.
cargo-deb] creates binary Debian packages
based on Cargo.toml, and can be configured by a deb metadata
section.cargo-rpm], which is differs from cargo-deb (besides producing
.rpm instead of .deb packages, of course) in not using Cargo.toml
for its metadata.debcargo], which clearly separates the packager and upstream roles,
by generating a template Debian source package from a "pristine"
crate source.So how does cargo-parcel relate to these tools? Creating actual
distribution packages is out of scope for cargo-parcel, instead it
intends to let you describe your application crates contents, so it
can be easily installed directly from source, and a simple,
distribution-agnostic binary package can be built for distribution.
Besides hopefully reducing the overhead of packaging "Rust
applications", having the cargo-parcel metadata available would also
allow building other potentially cool stuff. One idea would be a web
site focused on Rust applications (both CLI and GUI) which could:
docs.rs, but for end-user documentation, not API docs.Thinking about this also raised the question of "what's the scope of
cargo and crates.io" in my mind. I feel that dealing with platform
idiosyncrasies, such as the mere existence of man pages, is out of
cargo's scope. So if we accept that cargo will not deal with such
things as rendering and installing man pages, does that leave a gap
for a tool that does? cargo-parcel is an experiment in filling that
gap, currently tailored to the need of its author's CLI crates, but
intended to be useful for others as well.
If a tool similar to cargo-parcel, a cargo install tailored
towards applications written in Rust, were to take off, that would
mean binary crates will become (more) commonplace where running cargo
install will not be sufficient to (fully) install them. In that
hypothetical future, it might even make sense to think about providing
such crates via a channel separate from crates.io.
The code and documentation in this crate is free software, dual-licensed under the MIT or Apache-2.0 license, at your choosing.
The contents of the templates and examples directories are
intended for free copying and adaption, for any use, without any
obligations. The author considers these to be too trivial to fall
under copyright anyway.