Build From Source

Use this path when you want to build from a checkout, test local changes, or install a development build. The source workflow is Justfile-oriented; direct Cargo commands are shown only where they help explain what each target does.

For release binaries, use Installation Script or Manual Binary Install.

Requirements

Install:

• git
• Rust via rustup
• just
• Xray for runtime use; xrat setup can install it as a verified user-local tool
• sing-box or V2Ray when needed; setup can install these too

Install just with Cargo if your distribution does not package it:

cargo install just

Check the local task list:

just --list

Clone

git clone https://github.com/mhyrzt/xrat.git
cd xrat

Build

For a development build:

just build

For a release build using the locked dependency graph:

just release

The release binary is written to:

target/release/xrat

Run a local command from the checkout:

just run status

Install From Checkout

Build the current checkout and install it through install.sh:

just install

Pass installer flags after the recipe name:

just install --yes

By default, this installs to ~/.local/bin/xrat, plus generated man pages, shell completions, and desktop launcher assets. Override the binary directory with the installer flag:

just install --install-dir /usr/local/bin --yes

Skip desktop launcher assets with the installer flag:

just install --no-desktop --yes

Replace an existing Cargo-installed binary directly with Cargo:

just reinstall

Remove the Cargo-installed binary:

just uninstall

Ensure ~/.local/bin is in PATH for the installer path:

export PATH="$HOME/.local/bin:$PATH"

Add it to your shell startup file if xrat --version cannot find the installed binary.

Install Man Pages From Source

Generate and install man pages from the local command definitions:

just install-manpages

This writes pages to ~/.local/share/man/man1 and refreshes that man database when mandb is available. Existing xrat.1 and xrat-*.1 pages are removed first so renamed or removed commands do not leave stale man pages behind.

Install Completions From Source

The completions target prints generated completions for the requested shell. Redirect the output to the location your shell reads.

Bash

mkdir -p ~/.local/share/bash-completion/completions
just completions bash > ~/.local/share/bash-completion/completions/xrat

Open a new shell or source your Bash startup file.

Zsh

mkdir -p ~/.zfunc
just completions zsh > ~/.zfunc/_xrat

Add this to ~/.zshrc if needed:

fpath=("$HOME/.zfunc" $fpath)
autoload -Uz compinit
compinit

Fish

mkdir -p ~/.config/fish/completions
just completions fish > ~/.config/fish/completions/xrat.fish

First-Time Setup

Initialize the config directory and database:

xrat init

Install and start the systemd user daemon:

xrat daemon install --start

Then follow the Quickstart.

Source-Tree Checks

Run the same commands as .github/workflows/ci.yml:

just ci

That expands to:

just fmt-rust-check
just lint
just test

For broader local formatting checks across Rust, Markdown, and SQL:

just fmt-check

Useful supporting targets: