car·go·lin·er, noun:
- a cargo ship that sails regularly between designated ports according to a published schedule.
Summary
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
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.
Rationale
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 install
for all packages listed in that file.
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.
Installation
-
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.
-
Populate the file with packages you wish to be installed, for example:
[] = "*" = "~0.22" = "=0.71.0" = { = "0.6.2", = false, = ["native-tls", "postgres"] } = { = "13.0.0", = true }
or use
cargo liner import
to do it automatically for you, see below for more detailed explanations.
Usage
CLI
Some basic commands are now available:
)
)
Default command
When the subcommand is omitted, it will use the ship
subcommand with default
options.
Simply run cargo liner
in order to:
- Read packages from the configuration file.
- Run
cargo install
for each of them. - Self-update.
Example output if only git-journal
is required:
)
) )
)
)
ship
subcommand
The main command: do the installing and updating of packages.
)
Simply run cargo liner ship
in order to:
- Read packages from the configuration file.
- Run
cargo install
for each of them, respecting the version requirements. - Self-update only if
--no-self
is not given.
import
subcommand
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.
)
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:
[]
= "*"
= "*"
= "*"
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:
[]
= "~0.22.1"
= "~0.36.3"
= "~0.11.1"
The file can of course be edited manually afterwards, as intended.
Configuration
The file must be located at $CARGO_HOME/liner.toml
and contain a
properly-formed TOML document respecting the following format:
[]
= "version-req-1"
= "version-req-2"
= { = "version-req-3", = boolean, = boolean, = [ "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
.
Contributing
See the contributing guidelines. Please also take note of the code of conduct.
Copyright notice
Sergej Tucakov for the animation used as this project's logo.