Files

T

Eric Coissac 6acafa7f2c docs: add obikmer user guide and MkDocs build configuration

Introduces a comprehensive documentation set covering theoretical foundations, CLI usage, installation, and system architecture. Adds MkDocs configuration and Makefile targets to generate, serve with live reload, and clean the documentation site. Includes citation styles and bibliography files for academic references.

2026-08-13 17:19:01 +02:00

2.2 KiB

Raw Permalink Blame History

Installation

Prerequisites

Rust toolchain

obikmer requires Rust 1.85 or later (edition 2024). Install or update via rustup:

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

C build environment (required for hwloc)

obikmer embeds hwloc (Hardware Locality) for NUMA-aware thread placement on multi-socket machines. hwloc is built from source at compile time, which requires a standard C build environment.

Linux (Debian/Ubuntu)

apt install build-essential automake libtool autoconf pkg-config

Linux (RHEL/Rocky/AlmaLinux)

dnf install gcc make automake libtool autoconf pkgconfig

HPC clusters

Most HPC clusters provide these tools via the module system:

module load gcc automake libtool autoconf

If in doubt, check that autoreconf --version and libtool --version return successfully.

macOS

brew install automake libtool autoconf pkg-config

Building

git clone <repository-url>
cd obikmer/src
cargo build --release

The compiled binary is at target/release/obikmer.

Building on HPC clusters (network filesystems)

HPC home directories are typically on a network filesystem (Lustre, NFS) optimized for large sequential reads, not for the many small file operations Cargo generates during compilation. Building directly on such a filesystem can be extremely slow.

Redirect the build directory to a local scratch disk:

CARGO_TARGET_DIR=/scratch/$USER/cargo-target cargo build --release

Adapt the path to the scratch space available on your cluster (/var/tmp, /tmp, /scratch/local, etc.). Once built, copy the binary to a permanent location:

cp /scratch/$USER/cargo-target/release/obikmer ~/bin/

NUMA support

NUMA-aware thread placement is active automatically on multi-socket Linux machines, detected at runtime via hwloc. No build flag is required — it falls back gracefully to a single-pool strategy on:

macOS (Apple Silicon, unified memory)
single-socket Linux machines
any system where hwloc reports only one NUMA node

Verifying the installation

obikmer --help

2.2 KiB Raw Permalink Blame History