TOA Usage and Installation Guide

TOA is the latest rage for compression and archive why?

• It's written in Rust. Everybody likes Rust for some reason.
• It combines many compression formats with Reed-Solomon error correction
• It means in simple terms even if a file is corrupted you can regain it!
• You can set EXTREME levels of redundancy for that 99 year safe storage option!

Stuff like this should of been invented decades ago for floppy disks etc.

TOA Usage Guide

The reference implementation is available on GitHub at https://github.com/hasenbanck/toa. Pre-built binaries are provided for Linux (among other platforms), and the project remains experimental as of the latest releases, with an established version 1.0 specification.

Quick Installation on Linux

1. Visit the releases page: https://github.com/hasenbanck/toa/releases
2. Download the appropriate pre-built binary for your architecture (e.g., Linux x86_64).
3. Extract and place the toa executable in a directory on your PATH (e.g., /usr/local/bin), or run it directly from the download location.

No additional dependencies are typically required for basic usage.

Basic Usage

The primary command-line interface is the toa binary.

• Compress a file:
• Decompress a file:
• Verify integrity (including error correction):

toa c [options] input_file output.toa

toa d input.toa output_file

toa v input.toa

Key options include:

• -e <level> or --ecc <level>: Set error correction strength (e.g., percentage of recoverable data; higher values increase file size but improve resilience).
• -l <level>: Compression level (similar to xz; higher values yield better ratios at the cost of speed).
• Other flags support glob patterns for multiple files, streaming, and verbosity.

Error correction activates automatically during decompression if corruption is detected within the configured limits.

Ten Usage Examples

1. Basic compression of a single file with default settings
2. Compress with moderate error correction (10% recovery capability)
3. High compression with strong error correction for archival data
4. Compress multiple files using glob patterns
5. Decompress a TOA archive
6. Verify an archive and automatically repair minor corruption
7. Compress a directory by first creating a tar archive, then applying TOA
8. Stream compression for piping large data (e.g., from a backup tool)
9. Maximum compression for text-heavy data with light error correction
10. Repair and extract in one step (if corruption is within ECC limits)

toa c -e 10 large_backup.tar archive.toa

toa c -l 9 -e 20 important_database.sql.gz critical_archive.toa

toa c -e 15 logs/*.log logs_archive.toa

toa d recovered_data.toa extracted_directory/

toa v photos_backup.toa

tar cf - photos/ | toa c -e 15 > photos_archive.toa

rsync -a source/ - | toa c -e 8 > streaming_backup.toa

toa c -l 9 -e 5 source_code_directory.tar.xz code_archive.toa

toa d --repair damaged_archive.toa repaired_files/

For the most current options and detailed specification, consult the project's README and releases page on GitHub. As TOA is under active development, test critical data thoroughly before relying on it for irreplaceable archives.

Full Installation / Compiling Guide

The following provides a formal, step-by-step guide to installing the TOA compression tool on Linux. TOA is a modern compression format implemented in Rust, featuring high compression ratios (comparable to XZ), built-in Reed-Solomon error correction, streaming support, and parallel processing. The official implementation is available as a command-line utility hosted at https://github.com/hasenbanck/toa.

Three primary installation methods exist, ordered by convenience and recommendation for most users.

1. Recommended: Install Pre-built Binary (Fastest and Simplest)

Pre-compiled binaries for Linux (x86_64 and potentially aarch64) are provided in GitHub Releases. This method requires no additional dependencies beyond a web browser or command-line downloader.

Navigate to the releases page:
https://github.com/hasenbanck/toa/releases

Identify the latest release (e.g., v0.4.0 or newer, as of the most recent updates).

Under Assets, locate the appropriate binary for your architecture:

• Typically named similar to toa-x86_64-unknown-linux-gnu (for 64-bit Intel/AMD systems)
• Or toa-aarch64-unknown-linux-gnu (for ARM64 systems, such as Raspberry Pi 4/5 or certain cloud instances)

Download the file:

• Via browser, or using curl/wget in the terminal:

wget https://github.com/hasenbanck/toa/releases/download/vX.Y.Z/toa-x86_64-unknown-linux-gnu

(Replace vX.Y.Z with the actual version tag and adjust the filename as needed.)

Make the binary executable:

chmod +x toa-x86_64-unknown-linux-gnu

Move it to a directory in your PATH (recommended for system-wide access):

sudo mv toa-x86_64-unknown-linux-gnu /usr/local/bin/toa

Alternatively, place it in ~/bin or another personal bin directory and ensure that directory is in your PATH.

Verify the installation:

toa --version

or

toa --help

This method is ideal for most users, as it avoids compilation and dependency installation.

2. Install via Cargo (Rust Package Manager)

This method installs the latest published version from crates.io and is convenient if Rust is already present on your system.

Prerequisites
Rust and Cargo must be installed. If not present:

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

Follow the on-screen instructions, then restart your terminal or run:

source "$HOME/.cargo/env"

Installation steps

Install the TOA crate:

cargo install toa

Cargo automatically places the binary in ~/.cargo/bin/. Ensure this directory is in your PATH (it usually is added by rustup).

Verify:

toa --version

This method fetches a stable, published version and handles dependencies automatically.

3. Build from Source (For Development or Custom Builds)

Use this approach to access the absolute latest code or to modify the source.

Prerequisites

• Rust and Cargo (install via rustup as shown above)
• git

Steps

Clone the repository:

git clone https://github.com/hasenbanck/toa.git
cd toa

Build and install:

cargo install --path .

(This installs to ~/.cargo/bin/toa.)
Alternatively, build without installing:

cargo build --release

The binary will be located at ./target/release/toa.

Optionally, copy the release binary to /usr/local/bin/ for global access:

sudo cp target/release/toa /usr/local/bin/

Verify:

toa --version

Post-Installation Notes

Basic usage examples (consult toa --help for full options):

• Compress a file with default settings (includes error correction):

toa compress input.txt -o output.toa

• Decompress:

toa decompress output.toa -o restored.txt

• Adjust error correction level or other parameters via flags (e.g., --ecc-level).

Updates: Re-download the binary from releases, re-run cargo install toa, or pull and rebuild from source as needed.

Dependencies and compatibility: The tool is written in Rust and produces statically linked binaries in most cases, requiring no runtime libraries beyond the standard C library. It supports x86_64 and aarch64 Linux; SIMD optimizations (e.g., GFNI on x86_64, NEON on ARM) are automatically detected.

If you encounter any issues during installation (e.g., architecture mismatch or permission errors), or require guidance on usage scenarios such as batch processing or integrating TOA into scripts, please provide additional details for further assistance.