Binary installation for rust projects
Find a file
Jiahao XU d9cc3ce219
Refactor: Extract new crate binstalk-types plus other misc refactor and optimization ()
* Refactor: Extract new crate binstalk-types
* Optimize: Rm field `CrateInfo::other`
   which also removes dep serde-tuple-vec-map and serde-json from
   binstalk-types.
   
   This also makes `CrateInfo` easier to use, more generic and can be used
   over any `Serializer`, not just `serde_json::Value`.
* Mark all errors in `binstalk-manifests` as non_exhaustive
* Reduce size of `CvsParseError` by using `Box<str>`
   instead of `String` for variant `UnknownSourceType`.
* Reduce size of `CratesTomlParseError` to 16 bytes on 64bit platform
   by boxing variants `TomlWrite` and `CvsParse` as these two fields are
   significantly larger than other variants.
* Unify import style in mod `binstall_crates_v1`
* Replace dep binstalk-manifests with binstalk-types in binstalk-downloader
   to reduce its transitive dependencies and enables binstalk-downloader to
   be built in parallel to binstak-manifests.
* Replace dep binstalk-manifests with binstalk-types in binstalk
   to reduce transitive dependencies and enables binstalk to be built in
   parallel to binstalk-manifests.
   
   This is benefitial because binstalk-manifests pulls in toml_edit, which
   could takes up to 15s to be built on M1 (7-9s for codegen).
* Add dep binstalk-manifests to crates/bin
* Update dependabot and GHA release-pr

Signed-off-by: Jiahao XU <Jiahao_XU@outlook.com>
2022-11-17 13:46:27 +13:00
.cargo Swap macos to zip, update binary lookup for binstall 2021-10-08 11:38:38 +13:00
.github Refactor: Extract new crate binstalk-types plus other misc refactor and optimization () 2022-11-17 13:46:27 +13:00
crates Refactor: Extract new crate binstalk-types plus other misc refactor and optimization () 2022-11-17 13:46:27 +13:00
.editorconfig Split crates and clean up structure of codebase () 2022-08-20 11:24:12 +00:00
.gitignore Add .DS_Store to .gitignore 2022-06-12 22:38:34 +10:00
Cargo.lock Refactor: Extract new crate binstalk-types plus other misc refactor and optimization () 2022-11-17 13:46:27 +13:00
Cargo.toml Refactor: Extract new crate binstalk-types plus other misc refactor and optimization () 2022-11-17 13:46:27 +13:00
README.md Mention upgrade, fix () 2022-11-10 03:58:52 +00:00
SUPPORT.md Support default filename with underscores. () 2022-10-20 12:44:35 +11:00

Cargo B(inary)Install

cargo binstall provides a low-complexity mechanism for installing rust binaries as an alternative to building from source (via cargo install) or manually downloading packages. This is intended to work with existing CI artifacts and infrastructure, and with minimal overhead for package maintainers.

binstall works by fetching the crate information from crates.io, then searching the linked repository for matching releases and artifacts, with fallbacks to quickinstall and finally cargo install if these are not found. To support binstall maintainers must add configuration values to Cargo.toml to allow the tool to locate the appropriate binary package for a given version and target. See SUPPORT.md for more detail.

Status

Build GitHub tag Crates.io

You probably want to see this page as it was when the latest version was published for accurate documentation.

Installation

To get started using cargo-binstall first install the binary (either via cargo install cargo-binstall or by downloading a pre-compiled release), then extract it using tar or unzip and move it into $HOME/.cargo/bin. We recommend using the pre-compiled ones because we optimize those more than a standard source build does.

OS Arch URL
linux x86_64 https://github.com/cargo-bins/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-unknown-linux-musl.tgz
linux armv7 https://github.com/cargo-bins/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-unknown-linux-musl.tgz
linux arm64 https://github.com/cargo-bins/cargo-binstall/releases/latest/download/cargo-binstall-aarch64-unknown-linux-musl.tgz
macos x86_64 https://github.com/cargo-bins/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-apple-darwin.zip
macos m1 https://github.com/cargo-bins/cargo-binstall/releases/latest/download/cargo-binstall-aarch64-apple-darwin.zip
windows x86_64 https://github.com/cargo-bins/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-pc-windows-msvc.zip

To upgrade, use cargo binstall cargo-binstall!

Usage

Supported packages can be installed using cargo binstall NAME where NAME is the crates.io package name.

Package versions and targets may be specified using the --version and --target arguments respectively, and will be installed into $HOME/.cargo/bin by default. For additional options please see cargo binstall --help.

[garry] ➜  ~ cargo binstall radio-sx128x --version 0.14.1-alpha.5
21:14:15 [INFO] Resolving package: 'radio-sx128x'
21:14:18 [INFO] This will install the following binaries:
21:14:18 [INFO]   - sx128x-util (sx128x-util-x86_64-apple-darwin -> /Users/ryankurte/.cargo/bin/sx128x-util-v0.14.1-alpha.5)
21:14:18 [INFO] And create (or update) the following symlinks:
21:14:18 [INFO]   - sx128x-util (/Users/ryankurte/.cargo/bin/sx128x-util-v0.14.1-alpha.5 -> /Users/ryankurte/.cargo/bin/sx128x-util)
21:14:18 [INFO] Do you wish to continue? yes/[no]
? yes
21:14:20 [INFO] Installing binaries...
21:14:21 [INFO] Done in 6.212736s

Unsupported crates

Nowadays, cargo-binstall is smart enough. All you need just passing the crate name.

cargo binstall --no-confirm --no-symlinks cargo-edit cargo-watch cargo-tarpaulin \
    watchexec-cli cargo-outdated just fnm broot stylua

If your favorite package fails to install, you may specify the Cargo.toml metadata entries for pkg-url, bin-dir, and pkg-fmt at the command line, with values as documented below.

For example:

$ binstall \
  --pkg-url="{ repo }/releases/download/{ version }/{ name }-{ version }-{ target }.{ archive-format }" \
  --pkg-fmt="txz" crate_name

Upgrade installed crates

The most ergonomic way to upgrade the installed crates is with cargo-update. cargo-update automatically uses cargo-binstall to install the updates if cargo-binstall is present.

Supported crates such as cargo-binstall itself can also be updated with cargo-binstall as in the example in Installation above.

FAQ

  • Why use this?
    • Because wget-ing releases is frustrating, cargo install takes a not inconsequential portion of forever on constrained devices, and often putting together actual packages is overkill.
  • Why use the cargo manifest?
    • Crates already have these, and they already contain a significant portion of the required information. Also, there's this great and woefully underused (IMO) [package.metadata] field.
  • Is this secure?
    • Yes and also no? We're not (yet? #1) doing anything to verify the CI binaries are produced by the right person/organization. However, we're pulling data from crates.io and the cargo manifest, both of which are already trusted entities, and this is functionally a replacement for curl ... | bash or wget-ing the same files, so, things can be improved but it's also fairly moot
  • What do the error codes mean?
  • Can I use it in CI?
    • Yes! For GitHub Actions, we recommend the excellent taiki-e/install-action, which has explicit support for selected tools and uses cargo-binstall for everything else.

If you have ideas/contributions or anything is not working the way you expect (in which case, please include an output with --log-level debug) and feel free to open an issue or PR.