# dtox CLI Installation Guide

`dtox` is a standard Rust CLI binary, so the most portable way to install it is via `cargo install`. This document collects the exact commands for macOS, Windows, and the major Linux distributions.

> **Quick TL;DR:**
>
> ```sh
> cargo install --locked --git https://gitlab.com/hti-oss/rxdatasets/dtox.git --tag 0.7.0
> dtox --version
> ```
>
> The command works on any platform that has Rust installed. Drop `--tag 0.7.0` if you prefer tracking `master`.

## Prerequisites

- Rust toolchain with Cargo (`rustup` is the recommended installer).
- Git (available by default on macOS and most Linux distros; install "Git for Windows" or enable the optional Windows feature if needed).
- Network access to `https://gitlab.com/hti-oss/rxdatasets/dtox.git`.

If you are new to Rust, install it first:

```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

Windows users can run the same command from PowerShell or install via `winget install --id Rustlang.Rustup -e`.

## Helper Install Scripts

Two small helper scripts live in [`scripts/`](scripts) for convenience:

- [`scripts/install.sh`](scripts/install.sh): POSIX shell wrapper for Linux and macOS.
- [`scripts/install.ps1`](scripts/install.ps1): PowerShell wrapper for Windows or PowerShell Core on any OS.

Both wrappers default to the public GitLab repository URL and accept the following parameters:

| Option | Shell Script | PowerShell Script | Description |
| ------ | ------------ | ----------------- | ----------- |
| Pin version/tag | `-t 0.7.0` or `--tag 0.7.0` | `-Tag 0.7.0` | Installs the tagged release rather than the repository HEAD |
| Override repo URL | `-r <url>` or `--git-url <url>` | `-GitUrl <url>` | Point at a fork or mirror |
| Extra Cargo args | append `-- --root ~/.local` | `-CargoArgs @('--root','C:\dtox')` | Forwarded directly to `cargo install` |

You may also export `DTOX_REPO_URL` to override the default repo location globally before invoking either script.

## Linux & macOS

```sh
# clone or download the repo (optional but convenient)
git clone https://gitlab.com/hti-oss/rxdatasets/dtox.git
cd dtox

# install dependencies if rustup/cargo is missing, then:
./scripts/install.sh --tag 0.7.0

# add cargo bin dir to PATH if needed
export PATH="$HOME/.cargo/bin:$PATH"

dtox --version
```

The script prints the resolved command before running `cargo install`. Re-run it with `--force` (forwarded to Cargo) if you need to upgrade in place.

## Windows (PowerShell)

```powershell
# Optionally ensure rustup is installed first
winget install --id Rustlang.Rustup -e

# Clone and run the installer helper
git clone https://gitlab.com/hti-oss/rxdatasets/dtox.git
Set-Location dtox

# Bypass execution-policy prompts only for this session if necessary
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Tag 0.7.0

# Ensure %USERPROFILE%\.cargo\bin is on PATH, then verify
$env:PATH = "$Env:USERPROFILE\.cargo\bin;$env:PATH"
dtox --version
```

PowerShell Core users on macOS/Linux can call the same script; it behaves identically across platforms.

## Installing Without Cloning

You can install directly from GitLab without cloning by invoking Cargo yourself:

```sh
cargo install --locked --git https://gitlab.com/hti-oss/rxdatasets/dtox.git --tag 0.7.0
```

Pass `--force` to upgrade an existing installation or omit `--tag` to track `master`.

## Local Dev Builds

During development, the `just install` recipe installs from the current checkout:

```sh
just install
```

`cargo install --path . --locked --force` is executed under the hood, so your locally built changes become the active binary immediately.

## Uninstalling / Upgrading

- Upgrade in-place: `cargo install --locked --git https://gitlab.com/hti-oss/rxdatasets/dtox.git --tag 0.7.0 --force`
- Remove the binary: `cargo uninstall dtox`

## Verifying the Installation

Run `dtox --version`. The command exits with `0` and prints the semantic version embedded in `Cargo.toml`. Consider also running a smoke test on one of the fixtures:

```sh
dtox --input-dir tests/fixtures --output-dir /tmp/dtox-out --template-dir tests/fixtures
```

You now have a reproducible, cross-platform installation path that does not depend on Docker.
