Skip to content

Update README with maintenance information #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mxcl wants to merge 1 commit into
base: main
Choose a base branch
from
+1 −115
Open

Update README with maintenance information #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 1 addition & 115 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <crate[@version]> [--] [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 <name>`: 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