Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation

Install with Nix

See installing with Nix for the supported platforms, profile installation, and CPU-specific builds.

Install a prebuilt release binary

When a release is available, ordinary users can download the archive for their operating system and CPU from the GitHub Releases page. Archives are named rustiq-chem-<target>.tar.gz on Unix and rustiq-chem-<target>.zip on Windows. Supported targets are x86_64-unknown-linux-gnu (Linux Intel/AMD), aarch64-unknown-linux-gnu (Linux ARM64), x86_64-apple-darwin (Intel macOS), aarch64-apple-darwin (Apple Silicon), x86_64-pc-windows-msvc (Windows Intel/AMD), and aarch64-pc-windows-msvc (Windows ARM64). Linux GNU archives require a compatible glibc runtime.

RustiQ-authored code is MIT OR Apache-2.0. Executables include LGPL libraries, third-party notices and a matching corresponding-source archive on the same release page. See licenses and redistribution for source access, rebuilding and package redistribution requirements.

Verify and run the executable

Download the release’s sha256.sum beside the archive chosen for your platform. You do not need the archives for other platforms. Copy only the matching line from sha256.sum into a new text file named selected.sha256, preserving both the hash and filename. On Linux or macOS, verify it before extracting:

sha256sum --check selected.sha256  # Linux
shasum -a 256 --check selected.sha256  # macOS

On Windows, use PowerShell to compare the downloaded archive’s computed hash with its matching entry in sha256.sum:

$archive = "rustiq-chem-x86_64-pc-windows-msvc.zip"
$entries = @(Select-String -Path .\sha256.sum -SimpleMatch $archive)
if ($entries.Count -ne 1) { throw "Expected one checksum entry for $archive" }
$expected = ($entries[0].Line -split '\s+')[0]
$actual = (Get-FileHash ".\$archive" -Algorithm SHA256).Hash
if ($actual -ine $expected) { throw "SHA-256 mismatch for $archive" }
Write-Host "SHA-256 verified: $archive"

The release guide has the full platform-specific verification instructions. For Windows ARM64, replace the archive filename with rustiq-chem-aarch64-pc-windows-msvc.zip. Extract the archive only after the checksum comparison succeeds, then run ./rustiq --help from its directory on Linux or macOS, or .\rustiq.exe --help from that directory in PowerShell. To use rustiq from any directory, add the directory containing rustiq or rustiq.exe to PATH and open a new terminal.

The Cargo package is named rustiq-chem; the executable is named rustiq (or rustiq.exe on Windows).

Consult the manual

Release archives contain an offline HTML manual in manual/html/ beside the executable. Keep that directory with the executable when moving the extracted installation. The Nix package installs the same offline manual under share/doc/rustiq/manual/html. Navigation, styling, equations, and diagrams use local resources; external reference links require network access.

rustiq docs
rustiq docs --web
rustiq docs --print-path

rustiq docs opens the installed manual in the default browser using a browser-specific launcher, independently of HTML file associations. --web forces the online manual for the compiled release version; development builds use the development manual. The choice is made from the Cargo package version without a network lookup. Versions with a complete dev prerelease identifier, such as 0.1.0-alpha.1.dev, select /dev/. Other versions, including alpha and beta releases, select /vVERSION/. This applies equally to Cargo, Nix, and release archives, without packaging flags. A release-version source build selects its versioned manual even before publication. --print-path prints the absolute local index path without starting a browser; combine it with --web to print the online URL instead. On headless machines, copy the manual tree to another machine and open its index.html, or use the printed URL in a browser with network access.

Cargo-only installations have no bundled manual: rustiq docs opens the online manual and --print-path prints its URL. RustiQ does not download the manual. An existing manual directory with a missing index produces an error; restore the complete installation or use --web. If the whole manual directory has been removed, RustiQ cannot distinguish the installation from a Cargo install and uses the online manual.

If browser launching fails, the diagnostic includes the target and the --print-path route. RustiQ uses the operating system’s default browser opener. PDF export is future work and --pdf is not supported.

Make basis sets available

The archive contains neither sample inputs nor basis data. With network access, download a basis using rustiq basis download sto-3g. This command is available in online builds and requires network access. To work offline, import a local Basis Set Exchange JSON file with rustiq basis import /path/to/basis.json; import does not access the network. See the basis-set guide and the first calculation for a complete binary-only example.

Build and install from source

Contributors and users building from a checkout need Git, Rust through rustup, a C/C++ build toolchain, and CMake. Clone from a parent directory, then run Cargo commands from the checkout root. For complete prerequisite and platform details, see the manual setup.

git clone https://github.com/mveril/RustiQ.git
cd RustiQ
cargo build --locked

cargo build does not add the executable to PATH. To run without installing, prefix commands with cargo run --locked --, for example cargo run --locked -- --help. To install the package executable into Cargo’s binary directory:

cargo install --locked --path .
rustiq --help

The registry package is also named rustiq-chem; install from crates.io only when the relevant version has been published. See the development environments page for Nix, Docker, and other supported contributor setups.