From b3f6eb64ea11728a709d029b2d8403998bf53c5d Mon Sep 17 00:00:00 2001
From: ryan kurte <ryankurte@gmail.com>
Date: Sat, 6 Aug 2022 09:44:17 +1200
Subject: [PATCH 1/2] split docs, first step towards simplifying support
instructions
---
README.md | 173 +++++++----------------------------------------------
SUPPORT.md | 89 +++++++++++++++++++++++++++
2 files changed, 112 insertions(+), 150 deletions(-)
create mode 100644 SUPPORT.md
diff --git a/README.md b/README.md
index bf580b0e..a071848d 100644
--- a/README.md
+++ b/README.md
@@ -1,47 +1,39 @@
# 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.
-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 [Supporting Binary Installation](#Supporting-Binary-Installation) for instructions on how to support `binstall` in your projects.
-## Installing
+`binstall` works by fetching the crate information from `crates.io`, then searching the linked `repository` for matching releases and artifacts.
+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](./SUPPORT.md) for more detail.
-To get started _using_ `cargo-binstall`, first install the binary (either via `cargo install cargo-binstall` or by downloading a pre-compiled [release](https://github.com/ryankurte/cargo-binstall/releases).
-linux x86\_64:
-```
-wget https://github.com/ryankurte/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-unknown-linux-musl.tgz
-```
+## Status
-linux armv7:
-```
-wget https://github.com/ryankurte/cargo-binstall/releases/latest/download/cargo-binstall-armv7-unknown-linux-musleabihf.tgz
-```
+
+[](https://github.com/ryankurte/cargo-binstall)
+[](https://crates.io/crates/cargo-binstall)
+[](https://docs.rs/cargo-binstall)
-linux arm64:
-```
-wget https://github.com/ryankurte/cargo-binstall/releases/latest/download/cargo-binstall-aarch64-unknown-linux-musl.tgz
-```
+## Installation
-macos x86\_64:
-```
-wget https://github.com/ryankurte/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-apple-darwin.zip
-```
+To get started _using_ `cargo-binstall` first install the binary (either via `cargo install cargo-binstall` or by downloading a pre-compiled [release](https://github.com/ryankurte/cargo-binstall/releases)).
+
+
+| 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 |
-macos M1:
-```
-wget https://github.com/ryankurte/cargo-binstall/releases/latest/download/cargo-binstall-aarch64-apple-darwin.zip
-```
-windows x86\_64:
-```
-wget https://github.com/ryankurte/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-pc-windows-msvc.zip
-```
## Usage
-Supported packages can be installed using `cargo binstall NAME` where `NAME` is the crate.io package name.
+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 install directory with `--install-dir` (this defaults to `$HOME/.cargo/bin`, with fall-backs to `$HOME/.bin` if unavailable). For additional options please see `cargo binstall --help`.
+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
@@ -68,125 +60,6 @@ $ binstall \
--pkg-fmt="txz" crate_name
```
-## Status
-
-
-[](https://github.com/ryankurte/cargo-binstall)
-[](https://crates.io/crates/cargo-binstall)
-[](https://docs.rs/cargo-binstall)
-
-### Features
-
-- Manifest discovery
- - [x] Fetch crate / manifest via crates.io
- - [ ] Fetch crate / manifest via git (/ github / gitlab)
- - [x] Use local crate / manifest (`--manifest-path`)
- - [x] Fetch build from the [quickinstall](https://github.com/alsuren/cargo-quickinstall) repository
-- Package formats
- - [x] Tgz
- - [x] Txz
- - [x] Tbz2
- - [x] Tar.zst
- - [x] Tar
- - [x] Zip
- - [x] Bin
-- Extraction / Transformation
- - [x] Extract from subdirectory in archive (ie. support archives with platform or target subdirectories)
- - [x] Extract specific files from archive (ie. support single archive with multiple platform binaries)
-- Security
- - [ ] Package signing
- - [ ] Package verification
-- [x] Fallback to installing from source
-
-
-## Supporting Binary Installation
-
-`binstall` works with existing CI-built binary outputs, with configuration via `[package.metadata.binstall]` keys in the relevant crate manifest.
-When configuring `binstall` you can test against a local manifest with `--manifest-path=PATH` argument to use the crate and manifest at the provided `PATH`, skipping crate discovery and download.
-
-To get started, add a `[package.metadata.binstall]` section to your `Cargo.toml`. As an example, the default configuration would be:
-
-```toml
-[package.metadata.binstall]
-pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }-v{ version }.{ archive-format }"
-bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }"
-pkg-fmt = "tgz"
-```
-
-With the following configuration keys:
-
-- `pkg-url` specifies the package download URL for a given target/version, templated
-- `bin-dir` specifies the binary path within the package, templated (with an `.exe` suffix on windows)
-- `pkg-fmt` overrides the package format for download/extraction (defaults to: `tgz`)
-
-
-`pkg-url` and `bin-dir` are templated to support different names for different versions / architectures / etc.
-Template variables use the format `{ VAR }` where `VAR` is the name of the variable, with the following variables available:
-- `name` is the name of the crate / package
-- `version` is the crate version (per `--version` and the crate manifest)
-- `repo` is the repository linked in `Cargo.toml`
-- `bin` is the name of a specific binary, inferred from the crate configuration
-- `target` is the rust target name (defaults to your architecture, but can be overridden using the `--target` command line option if required()
-- `archive-format` is the filename extension of the package archive format
-- `binary-ext` is the string `.exe` if the `target` is for Windows, or the empty string otherwise
-- `format` is a soft-deprecated alias for `archive-format` in `pkg-url`, and for `binary-ext` in `bin-dir`; in the future this may warn at install time.
-
-`pkg-url`, `pkg-fmt` and `bin-dir` can be overridden on a per-target basis if required, for example, if your `x86_64-pc-windows-msvc` builds use `zip` archives this could be set via:
-
-```
-[package.metadata.binstall.overrides.x86_64-pc-windows-msvc]
-pkg-fmt = "zip"
-```
-
-### Defaults
-
-By default `binstall` is setup to work with github releases, and expects to find:
-
-- an archive named `{ name }-{ target }-v{ version }.{ archive-format }`
- - so that this does not overwrite different targets or versions when manually downloaded
-- located at `{ repo }/releases/download/v{ version }/`
- - compatible with github tags / releases
-- containing a folder named `{ name }-{ target }-v{ version }`
- - so that prior binary files are not overwritten when manually executing `tar -xvf ...`
-- containing binary files in the form `{ bin }{ binary-ext }` (where `bin` is the cargo binary name and `binary-ext` is `.exe` on windows and empty on other platforms)
-
-If your package already uses this approach, you shouldn't need to set anything.
-
-### QuickInstall
-
-[QuickInstall](https://github.com/alsuren/cargo-quickinstall) is an unofficial repository of prebuilt binaries for Crates, and `binstall` has built-in support for it! If your crate is built by QuickInstall, it will already work with `binstall`. However, binaries as configured above take precedence when they exist.
-
-### Examples
-
-For example, the default configuration (as shown above) for a crate called `radio-sx128x` (version: `v0.14.1-alpha.5` on x86\_64 linux) would be interpolated to:
-
-- A download URL of `https://github.com/rust-iot/rust-radio-sx128x/releases/download/v0.14.1-alpha.5/rust-radio-sx128x-x86_64-unknown-linux-gnu-v0.14.1-alpha.5.tgz`
-- Containing a single binary file `rust-radio-sx128x-x86_64-unknown-linux-gnu-v0.14.1-alpha.5/rust-radio-x86_64-unknown-linux-gnu`
-- Installed to`$HOME/.cargo/bin/rust-radio-sx128x-v0.14.1-alpha.5`
-- With a symlink from `$HOME/.cargo/bin/rust-radio-sx128x`
-
-#### If the package name does not match the crate name
-
-As is common with libraries / utilities (and the `radio-sx128x` example), this can be overridden by specifying the `pkg-url`:
-
-```toml
-[package.metadata.binstall]
-pkg-url = "{ repo }/releases/download/v{ version }/sx128x-util-{ target }-v{ version }.{ archive-format }"
-```
-
-Which provides a download URL of: `https://github.com/rust-iot/rust-radio-sx128x/releases/download/v0.14.1-alpha.5/sx128x-util-x86_64-unknown-linux-gnu-v0.14.1-alpha.5.tgz`
-
-
-#### If the package structure differs from the default
-
-Were the package to contain binaries in the form `name-target[.exe]`, this could be overridden using the `bin-dir` key:
-
-```toml
-[package.metadata.binstall]
-bin-dir = "{ bin }-{ target }{ binary-ext }"
-```
-
-Which provides a binary path of: `sx128x-util-x86_64-unknown-linux-gnu[.exe]`. It is worth noting that binary names are inferred from the crate, so long as cargo builds them this _should_ just work.
## FAQ
@@ -197,9 +70,9 @@ Which provides a binary path of: `sx128x-util-x86_64-unknown-linux-gnu[.exe]`. I
- 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 / organisation.
+ - Yes and also no? We're not (yet? [#1](https://github.com/cargo-bins/cargo-binstall/issues/1)) doing anything to verify the CI binaries are produced by the right person / organisation.
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 sorta moot
+ 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?
- You can find a full description of errors including exit codes here: <https://docs.rs/cargo-binstall/latest/cargo_binstall/errors/enum.BinstallError.html>
diff --git a/SUPPORT.md b/SUPPORT.md
new file mode 100644
index 00000000..7c2c871e
--- /dev/null
+++ b/SUPPORT.md
@@ -0,0 +1,89 @@
+# Support for `cargo binstall`
+
+
+`binstall` works with existing CI-built binary outputs, with configuration via `[package.metadata.binstall]` keys in the relevant crate manifest.
+When configuring `binstall` you can test against a local manifest with `--manifest-path=PATH` argument to use the crate and manifest at the provided `PATH`, skipping crate discovery and download.
+
+To get started, add a `[package.metadata.binstall]` section to your `Cargo.toml`. As an example, the default configuration would be:
+
+```toml
+[package.metadata.binstall]
+pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }-v{ version }.{ archive-format }"
+bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }"
+pkg-fmt = "tgz"
+```
+
+With the following configuration keys:
+
+- `pkg-url` specifies the package download URL for a given target/version, templated
+- `bin-dir` specifies the binary path within the package, templated (with an `.exe` suffix on windows)
+- `pkg-fmt` overrides the package format for download/extraction (defaults to: `tgz`)
+
+
+`pkg-url` and `bin-dir` are templated to support different names for different versions / architectures / etc.
+Template variables use the format `{ VAR }` where `VAR` is the name of the variable, with the following variables available:
+- `name` is the name of the crate / package
+- `version` is the crate version (per `--version` and the crate manifest)
+- `repo` is the repository linked in `Cargo.toml`
+- `bin` is the name of a specific binary, inferred from the crate configuration
+- `target` is the rust target name (defaults to your architecture, but can be overridden using the `--target` command line option if required()
+- `archive-format` is the filename extension of the package archive format
+- `binary-ext` is the string `.exe` if the `target` is for Windows, or the empty string otherwise
+- `format` is a soft-deprecated alias for `archive-format` in `pkg-url`, and for `binary-ext` in `bin-dir`; in the future this may warn at install time.
+
+`pkg-url`, `pkg-fmt` and `bin-dir` can be overridden on a per-target basis if required, for example, if your `x86_64-pc-windows-msvc` builds use `zip` archives this could be set via:
+
+```
+[package.metadata.binstall.overrides.x86_64-pc-windows-msvc]
+pkg-fmt = "zip"
+```
+
+### Defaults
+
+By default `binstall` is setup to work with github releases, and expects to find:
+
+- an archive named `{ name }-{ target }-v{ version }.{ archive-format }`
+ - so that this does not overwrite different targets or versions when manually downloaded
+- located at `{ repo }/releases/download/v{ version }/`
+ - compatible with github tags / releases
+- containing a folder named `{ name }-{ target }-v{ version }`
+ - so that prior binary files are not overwritten when manually executing `tar -xvf ...`
+- containing binary files in the form `{ bin }{ binary-ext }` (where `bin` is the cargo binary name and `binary-ext` is `.exe` on windows and empty on other platforms)
+
+If your package already uses this approach, you shouldn't need to set anything.
+
+### QuickInstall
+
+[QuickInstall](https://github.com/alsuren/cargo-quickinstall) is an unofficial repository of prebuilt binaries for Crates, and `binstall` has built-in support for it! If your crate is built by QuickInstall, it will already work with `binstall`. However, binaries as configured above take precedence when they exist.
+
+### Examples
+
+For example, the default configuration (as shown above) for a crate called `radio-sx128x` (version: `v0.14.1-alpha.5` on x86\_64 linux) would be interpolated to:
+
+- A download URL of `https://github.com/rust-iot/rust-radio-sx128x/releases/download/v0.14.1-alpha.5/rust-radio-sx128x-x86_64-unknown-linux-gnu-v0.14.1-alpha.5.tgz`
+- Containing a single binary file `rust-radio-sx128x-x86_64-unknown-linux-gnu-v0.14.1-alpha.5/rust-radio-x86_64-unknown-linux-gnu`
+- Installed to`$HOME/.cargo/bin/rust-radio-sx128x-v0.14.1-alpha.5`
+- With a symlink from `$HOME/.cargo/bin/rust-radio-sx128x`
+
+#### If the package name does not match the crate name
+
+As is common with libraries / utilities (and the `radio-sx128x` example), this can be overridden by specifying the `pkg-url`:
+
+```toml
+[package.metadata.binstall]
+pkg-url = "{ repo }/releases/download/v{ version }/sx128x-util-{ target }-v{ version }.{ archive-format }"
+```
+
+Which provides a download URL of: `https://github.com/rust-iot/rust-radio-sx128x/releases/download/v0.14.1-alpha.5/sx128x-util-x86_64-unknown-linux-gnu-v0.14.1-alpha.5.tgz`
+
+
+#### If the package structure differs from the default
+
+Were the package to contain binaries in the form `name-target[.exe]`, this could be overridden using the `bin-dir` key:
+
+```toml
+[package.metadata.binstall]
+bin-dir = "{ bin }-{ target }{ binary-ext }"
+```
+
+Which provides a binary path of: `sx128x-util-x86_64-unknown-linux-gnu[.exe]`. It is worth noting that binary names are inferred from the crate, so long as cargo builds them this _should_ just work.
From 5c703f30ca5912c6d753700eb3e56f04d58d4fbb Mon Sep 17 00:00:00 2001
From: ryan kurte <ryankurte@gmail.com>
Date: Mon, 8 Aug 2022 11:42:06 +1200
Subject: [PATCH 2/2] add note about quickinstall / cargo install fallback
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index a071848d..e0378c81 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
`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.
+`binstall` works by fetching the crate information from `crates.io`, then searching the linked `repository` for matching releases and artifacts, with fallbacks to [quickinstall](https://github.com/alsuren/cargo-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](./SUPPORT.md) for more detail.