diff --git a/README.md b/README.md index 7c4966c..70d6de3 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,3 @@ # `cargox` -[![CI](https://github.com/mxcl/cargox/actions/workflows/ci.yml/badge.svg)](https://github.com/mxcl/cargox/actions/workflows/ci.yml) -[![Crates.io](https://img.shields.io/crates/v/cargox-cli.svg)](https://crates.io/crates/cargox-cli) - -`cargox` runs Rust binaries on demand, installing them automatically if necessary. -It mirrors the convenience of `npx` for the Cargo ecosystem while prioritising -`cargo-binstall` to download prebuilt executables whenever possible. - -## Installation - -We recommend installing cargo-binstall as well, this significantly speeds up -use of `cargox`: - -```sh -cargo install cargo-binstall -cargo binstall cargox-cli -``` - -If you don’t want that then you can just `cargo install cargox-cli`. - -## Features - -- Executes `crate[@version]` binaries, installing them on demand. -- Prefers `cargo-binstall` for fast installs falling back to `cargo install`. -- Passes through additional arguments to the invoked binary via `--`. - -## Usage - -```bash -cargox [--] [binary-args...] -``` - -Examples: - -```bash -# Run the latest bat that is installed or installing the latest bat if necessary -$ cargox bat ./README.md - -$ cargox bat@latest ./README.md -# If the installed bat is old we only check for newer if you do this. -# This is how every foo*x* tool works. We are not being different. - -# Install and run a pinned version -$ cargox cargo-deny@0.16.3 check - -# Force a reinstall, building from source instead of using cargo-binstall -$ cargox --force --build-from-source cargo-nextest -# ^^ shorter: cargox -fs cargo-nextest -``` - -> [!TIP] -> -> - Arguments before the first positional are passed to `cargox`. -> - Arguments after the positional argument are passed to the invoked binary. -> - You can use `--` if necessary to define this separation point. - -### Flags - -- `--bin `: choose a specific binary when a crate exposes several. -- `-f`, `--force`: reinstall even if the binary already exists on `PATH`. -- `-q`, `--quiet`: suppress installer output (still prints a short status line). -- `-s`, `--build-from-source`: build from source using `cargo install` instead of `cargo-binstall`. - -## Versioned Installs - -Every binary installed by `cargox` is stored with an explicit version suffix. For example, running `cargox bat@0.24.0` produces `bin/bat-0.24.0` under the install root. When you invoke `cargox bat` without a version, the newest installed version is selected automatically. The special specifier `@latest` triggers a crates.io lookup to install and run the newest published release if a newer one exists. - -## Where Binaries Are Stored - -`cargox` operates in a **completely sandboxed environment**, isolated from your -system's Cargo installation. This ensures that binaries installed by `cargox` are -separate and don't interfere with your regular `cargo install` workflow. - -**Default install locations:** - -- **Linux/Unix**: `~/.local/share/cargox/bin` (XDG Data Directory) -- **macOS**: `~/Library/Application Support/cargox/bin` -- **Windows**: `%APPDATA%\cargox\bin` - -**Customizing the install directory:** - -You can override the default by setting: - -- `CARGOX_INSTALL_DIR`: Custom location for `cargox` installations - -**Complete sandboxing:** - -`cargox` ensures complete isolation by: - -1. **Not checking standard Cargo directories**: Binaries in `~/.cargo/bin`, - `~/.local/bin`, `/usr/local/bin`, or `CARGO_HOME/bin` are ignored when looking - for already-installed binaries. - -2. **Binary lookup is restricted to**: - - The `cargox` install directory only - -3. **Environment isolation**: When installing packages, `cargox` removes all - Cargo-related environment variables (like `CARGO_INSTALL_ROOT`, `CARGO_HOME`, - `BINSTALL_INSTALL_PATH`, etc.) to prevent any leakage into the installation - process. Only the controlled `cargox` install directory is set. - -This sandboxing guarantees that: - -- You can test different versions without affecting your system installations -- `cargox` binaries won't accidentally shadow your regular Cargo binaries -- The installation process is predictable and reproducible - -**Build artifact cleanup:** - -`cargox` automatically cleans up build artifacts after installation: - -- When using `cargo-binstall`, binaries are downloaded pre-built (no artifacts to clean) -- When using `cargo install`, build artifacts are placed in a temporary directory - that is automatically cleaned up after installation completes - -This keeps your system clean and prevents build cache bloat. +Maintained here -> https://github.com/mxcl/cargox