car·go·lin·er, noun:
- a cargo ship that sails regularly between designated ports according to a published schedule.
Cargo Liner is a tool to help one who has packages currently installed or to be
installed through the official cargo install
command to install and maintain
them up-to-date by editing a small and stable configuration file located at
$CARGO_HOME/liner.toml
.
Goals:
- Simple and intuitive API.
- Stable configuration file: avoid editing it automatically.
- Actually use
cargo install
,cargo search
orcargo config get
and not much else.
Non-goals:
- Super-duper stability guarantees.
- Re-implementing half of Cargo for small functionalities.
- Being """pretty""" above all else.
- Handling the synchronization of the configuration file between various hosts.
cargo install
works very well to download, compile and install a binary
package. However, it does not offer means to update currently installed
programs without having to specify them manually one by one on the CLI. That
becomes quickly bothersome when having to maintain several packages up-to-date,
especially if it needs to be done on multiple workstations.
Some projects, such as cargo-update or cargo-updater, exist in order to
solve this issue. Their strategy is to exploit the $CARGO_HOME/.crates.toml
and $CARGO_HOME/.crates2.json
files that Cargo generates and maintains in
order to track which packages are installed, their exact version, where they
were downloaded from and which programs they have installed. This strategy is
quite effective, so if you are looking for exactly that, then check them out.
However, some problems are still not solved like this: when configuring a new workstation, there is still the need to specify each package manually at least once; when adding a new package on one already-configured workstation, there is still the need to install it manually on all others. These tools lack sharing and synchronization.
The current project therefore inspires itself from tools such as zplug for
Zsh and vim-plug for Vim by taking orders from a central configuration file.
The tool then simply runs cargo search
for all packages listed in that file
in order to retrieve their latest versions available and then cargo install
for those that do indeed need an install or update using the results from the
search. That enables one to install and maintain all packages up-to-date, but
also to keep all of one's workstations synchronized by sharing the file between
them in some way, using Git for example.
-
Run:
cargo install cargo-liner
. -
Create the configuration file to be located at:
$CARGO_HOME/liner.toml
.- See the reference documentation about Cargo Home if you have trouble locating the directory.
-
If you are using a different Cargo installation root than
$CARGO_HOME
, please make sure it is properly configured in the$CARGO_INSTALL_ROOT
environment variable or theinstall.root
key of the$CARGO_HOME/config.toml
file so that the current tool may be able to detect that on itself. See thecargo install
documentation for more details about this. -
Populate the file with packages you wish to be installed, for example:
[packages] cargo-expand = "*" cargo-tarpaulin = "~0.22" nu = "=0.71.0" ripgrep = { version = "13.0.0", all-features = true } sqlx-cli = { version = "0.6.2", default-features = false, features = ["native-tls", "postgres"], }
or use
cargo liner import
to do it automatically for you, see below for more detailed explanations.
A few commands are available:
$ cargo help liner
Cargo subcommand to install and update binary packages listed in
configuration.
Usage: cargo liner [OPTIONS] [COMMAND]
Commands:
ship The default command if omitted: install and update
configured packages
import Import the `$CARGO_HOME/.crates.toml` Cargo-edited save
file as a new Liner configuration file
help Print this message or the help of the given
subcommand(s)
Options:
-v, --verbose...
Be more verbose. Use multiple times to be more and more so
each time.
When omitted, INFO and above messages of only this crate
are logged. When used once, DEBUG and above messages of
only this crate are logged and error backtraces are shown
(`RUST_BACKTRACE=1`). When used twice, DEBUG and above
messages of all crates are logged, `-v` is given to Cargo
calls (details ran commands), and error backtraces are
fully shown (`RUST_BACKTRACE=full`). When used three times
or more, TRACE and above messages of all crates are logged,
`-vv` is given to Cargo calls (includes build output) and
error backtraces are fully shown (`RUST_BACKTRACE=full`).
This takes precedence over the environment.
-q, --quiet...
Be quieter. Use multiple times to be more and more so each
time.
When omitted, INFO and above messages of only this crate
are logged. When used once, WARN and above messages of only
this crate are logged. When used twice, ERROR messages of
all crates are logged. When used three times or more, no
message will be logged, including Cargo's by passing `-q`
to it and error reports are silenced. This takes precedence
over the environment.
--color <WHEN>
Control the coloring of the logging output.
This enables one to manually specify when should the logs
and error reports be colored or not, for example if the
automatic detection is either not wished or not functional.
The value is also passed onto calls to Cargo.
[default: auto]
[possible values: auto, always, never]
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
When the subcommand is omitted, it will use the ship
subcommand with default
options. See its specific documentation for more details.
Simply run cargo liner
in order to:
- Read packages from the configuration file.
- Detect currently-installed packages from Cargo's installation.
- Check the latest available version for each of them.
- Install or update the ones that need to, respecting the version requirements.
- Self-update.
Example output if bat
and cargo-expand
are required:
$ cargo liner
INFO cargo_liner::cargo > Fetching latest package versions...
...
INFO cargo_liner > Results:
┌──────────────┬──────────────────┐
│ Name │ Status │
├──────────────┼──────────────────┤
│ bat │ ø -> 0.24.0 │
│ cargo-expand │ 1.0.78 -> 1.0.79 │
│ cargo-liner │ ✔ 0.0.0 │
└──────────────┴──────────────────┘
INFO cargo_liner::cargo > Installing `bat`...
Updating [..] index
Downloading crates ...
Downloaded bat v0.24.0 (registry [..])
Installing bat v0.24.0
Updating [..] index
...
Compiling bat v0.24.0
Finished release [optimized] target(s) in [..]s
Installing [..]/.cargo/bin/bat
Installed package `bat v0.24.0` (executable `bat`)
...
INFO cargo_liner::cargo > Updating `cargo-expand`...
Updating [..] index
Downloading crates ...
Downloaded cargo-expand v1.0.79 (registry [..])
Installing cargo-expand v1.0.79
Updating [..] index
...
Compiling cargo-expand v1.0.79
Finished release [optimized] target(s) in [..]s
Replacing [..]/.cargo/bin/cargo-expand
Replaced package `cargo-expand v1.0.78` with `cargo-expand v1.0.79` (executable `cargo-expand`)
...
INFO cargo_liner > Done.
The main command: do the installing and updating of packages.
$ cargo liner help ship
The default command if omitted: install and update configured
packages.
Self-updating is enabled by default.
Usage: cargo liner ship [OPTIONS]
Options:
-n, --no-self
Disable self-updating.
Cannot be used in conjunction with `--only-self`. Default:
`false`, i.e. self-update.
-s, --only-self
Only self-update and do not install or update any other
package.
Cannot be used in conjunction with `--no-self`. Default:
`false`, i.e. install or update other packages as well.
-c, --skip-check
Skip the summary version check and directly call `cargo
install` on each configured package.
The version check is relatively quick and enables skipping
calls to `cargo install` when no update is required, which
saves quite a bit of time. However, if you wish, this
option is still available in order not to run the check:
doing so will probably take more time in the end most of
the time, except if you have a very small amount of
packages configured (e.g. one or two) or if all or almost
all packages are not already installed.
It can also be used as a workaround in case a certain
operation fails in your particular environment, for
example: reading from `.crates.toml` under the
`$CARGO_HOME` or `$CARGO_INSTALL_ROOT` directory or making
requests to the registry. These operations will thus be
entirely skipped.
-f, --force
Force overwriting existing crates or binaries.
Passes the option flag onto each call of `cargo install`.
It will, for example, redownload, recompile and reinstall
every configured package when used in conjunction with
`--skip-check`.
-v, --verbose...
Be more verbose. Use multiple times to be more and more so
each time.
When omitted, INFO and above messages of only this crate
are logged. When used once, DEBUG and above messages of
only this crate are logged and error backtraces are shown
(`RUST_BACKTRACE=1`). When used twice, DEBUG and above
messages of all crates are logged, `-v` is given to Cargo
calls (details ran commands), and error backtraces are
fully shown (`RUST_BACKTRACE=full`). When used three times
or more, TRACE and above messages of all crates are logged,
`-vv` is given to Cargo calls (includes build output) and
error backtraces are fully shown (`RUST_BACKTRACE=full`).
This takes precedence over the environment.
-q, --quiet...
Be quieter. Use multiple times to be more and more so each
time.
When omitted, INFO and above messages of only this crate
are logged. When used once, WARN and above messages of only
this crate are logged. When used twice, ERROR messages of
all crates are logged. When used three times or more, no
message will be logged, including Cargo's by passing `-q`
to it and error reports are silenced. This takes precedence
over the environment.
--color <WHEN>
Control the coloring of the logging output.
This enables one to manually specify when should the logs
and error reports be colored or not, for example if the
automatic detection is either not wished or not functional.
The value is also passed onto calls to Cargo.
[default: auto]
[possible values: auto, always, never]
-h, --help
Print help (see a summary with '-h')
Simply run cargo liner ship
in order to:
- Read packages from the configuration file.
- Read currently installed packages from the Cargo-managed
.crates.toml
file under the$CARGO_INSTALL_ROOT
directory ifcargo config get
is able to retrieve its value from either the environment variable or theinstall.root
configuration item in$CARGO_HOME/config.toml
, or fall back to searching the file under the default$CARGO_HOME
directory if the first attempt fails for any reason, the simple absence of the setting being one of them. See thecargo install
documentation for more details about this. Whenever the first attempt fails, it is logged as aDEBUG
message before attempting the default, so use-vv
to investiguate if your configuration seems not to be taken into account. - Check the latest available version for each of them using
cargo search
. - Run
cargo install
for each that needs an install or update, respecting the version requirements. - Self-update only if
--no-self
is not given.
This command is meant to be used upon installing the tool and using it for the first time: it populates the configuration file with currently-installed packages.
$ cargo liner help import
Import the `$CARGO_HOME/.crates.toml` Cargo-edited save file as a new
Liner configuration file.
Star versions are used by default. The version transformation options
are mutually exclusive.
Usage: cargo liner import [OPTIONS]
Options:
-e, --exact
Import package versions as "exact versions", i.e. prepended
with an equal operator.
Cannot be used in conjunction with either `--compatible` or
`--patch`. Default: `false`, i.e. use a star requirement.
-c, --compatible
Import package versions as "compatible versions", i.e.
prepended with a caret operator.
Cannot be used in conjunction with either `--exact` or
`--patch`. Default: `false`, i.e. use a star requirement.
-p, --patch
Import package versions as "patch versions", i.e. prepended
with a tilde operator.
Cannot be used in conjunction with either `--exact` or
`--compatible`. Default: `false`, i.e. use a star
requirement.
-f, --force
Overwrite the current configuration file if it already
exists.
Default: `false`, i.e. return an error in case the file
already exists.
-s, --keep-self
Also import this `cargo-liner` package into the
configuration, for example in order to specify a certain
version requirement later on.
Default: `false`, i.e. exclude the current package from the
list of packages to install or update in the resulting
configuration file. Note however that the `ship` command
will still self-update by default.
-l, --keep-local
Also import all locally-installed packages into the
configuration. This means packages installed via `cargo
install --path <path>` will be present in the
configuration.
Default: `false`, i.e. exclude all packages installed via
`cargo install --path <path>` from the list of packages to
install or update in the resulting configuration file.
-v, --verbose...
Be more verbose. Use multiple times to be more and more so
each time.
When omitted, INFO and above messages of only this crate
are logged. When used once, DEBUG and above messages of
only this crate are logged and error backtraces are shown
(`RUST_BACKTRACE=1`). When used twice, DEBUG and above
messages of all crates are logged, `-v` is given to Cargo
calls (details ran commands), and error backtraces are
fully shown (`RUST_BACKTRACE=full`). When used three times
or more, TRACE and above messages of all crates are logged,
`-vv` is given to Cargo calls (includes build output) and
error backtraces are fully shown (`RUST_BACKTRACE=full`).
This takes precedence over the environment.
-q, --quiet...
Be quieter. Use multiple times to be more and more so each
time.
When omitted, INFO and above messages of only this crate
are logged. When used once, WARN and above messages of only
this crate are logged. When used twice, ERROR messages of
all crates are logged. When used three times or more, no
message will be logged, including Cargo's by passing `-q`
to it and error reports are silenced. This takes precedence
over the environment.
--color <WHEN>
Control the coloring of the logging output.
This enables one to manually specify when should the logs
and error reports be colored or not, for example if the
automatic detection is either not wished or not functional.
The value is also passed onto calls to Cargo.
[default: auto]
[possible values: auto, always, never]
-h, --help
Print help (see a summary with '-h')
For example, if you had previously installed:
bat@0.22.1
cargo-make@0.36.3
cargo-outdated@0.11.1
Then running cargo liner import
will result in the following configuration
file, if it does not already exist:
[packages]
bat = "*"
cargo-make = "*"
cargo-outdated = "*"
The command will by default import them with star version requirements. The
--exact
, --compatible
and --patch
options are provided in order to
customize how the currently-installed versions are imported into version
requirements: --exact
will prepend them with =
, --compatible
with ^
,
and --patch
with ~
.
For example, using the previous three packages already installed, running
cargo liner import --patch
would give:
[packages]
bat = "~0.22.1"
cargo-make = "~0.36.3"
cargo-outdated = "~0.11.1"
The file can of course be edited manually afterwards, as intended.
The file must be located at $CARGO_HOME/liner.toml
and contain a
properly-formed TOML document respecting the following format:
[packages]
package-name-1 = "version-req-1"
package-name-2 = "version-req-2"
package-name-3 = {
version = "version-req-3",
all-features = boolean,
default-features = boolean,
features = ["feature-1", "feature-2"],
}
#...
where:
package-name-*
must be a valid package name, i.e. match[a-zA-Z][a-zA-Z0-9_-]*
or something like that.version-req-*
must be a valid SemVer requirement, Cargo style. In particular, the catch-all wildcard*
can be used to require the latest version available.feature-*
must be the name of a cargo feature defined by the crate being installed.boolean
is a toml boolean, eithertrue
orfalse
.
See the contributing guidelines. Please also take note of the code of conduct.
Sergej Tucakov for the animation used as this project's logo.