Installation

hipoq is a Rust program. On Linux you can download a prebuilt binary and run it; on macOS you build it from source, which needs only a Rust toolchain.

Download a binary (Linux)

Two sources, both statically linked and both for either architecture:

• A release — a fixed, tagged version that will not change under you. Get it from the releases page; this is the one to use on a farm or in a script.
• The latest main build — what CI produced from the newest commit, below.

Architecture	Latest main
x86_64 (Intel/AMD — ifarm, most clusters)	hipoq-x86_64-linux
aarch64 (ARM64)	hipoq-aarch64-linux

Download under the artifact's own name — the checksum file names it that way, so keeping the name is what lets sha256sum -c work in the next step.

Note -o NAME rather than -O. The URL carries a ?job= query, and whether curl -O strips it from the saved filename depends on the curl version: 8.x does, but 7.76 — which is what AlmaLinux 9 and so ifarm ship — does not, and writes a file literally called hipoq-x86_64-linux?job=release:linux-x86_64. Naming the output explicitly behaves the same everywhere.

base=https://code.jlab.org/hallb/clas12/hipoq/-/jobs/artifacts/main/raw/dist
curl -L -o hipoq-x86_64-linux "$base/hipoq-x86_64-linux?job=release:linux-x86_64"
chmod +x hipoq-x86_64-linux
./hipoq-x86_64-linux --version

That is the whole install — no Rust, no C compiler, no shared libraries. Rename it to hipoq and move it onto your PATH when you are happy with it.

Why these run on ifarm when a normal build does not

They are statically linked against musl, so they depend on no system libc at all. This matters more than it sounds: the CI image is Debian bookworm (glibc 2.36) and ifarm2402 is AlmaLinux 9.7 (glibc 2.34), so an ordinary cargo build --release in CI would produce a binary that refuses to start on the farm. A musl binary runs on any Linux of its architecture, old or new.

They are not slower than building it yourself

A musl binary would normally be, because musl's allocator is much slower than glibc's under the threaded allocation churn that decompressing HIPO records produces — measured at 40–50% slower on filtered reads over a 9.1 GB DST. The published binaries are therefore built with mimalloc, which recovers all of it: against a native glibc build on the same node the difference is inside run-to-run noise, with peak memory unchanged.

Each build publishes a checksum alongside it, so you can confirm the download. The checksum file names the binary as hipoq-x86_64-linux, so verify before renaming it — otherwise sha256sum -c reports FAILED open or read, which reads like a corrupt download when it only means the file is not there under that name:

curl -L -o hipoq-x86_64-linux.sha256 "$base/hipoq-x86_64-linux.sha256?job=release:linux-x86_64"
sha256sum -c hipoq-x86_64-linux.sha256   # -> hipoq-x86_64-linux: OK
mv hipoq-x86_64-linux hipoq

macOS

There is no prebuilt macOS binary, and this is a limitation of where the builds run rather than an oversight: JLab's GitLab runners are Linux containers, and Rust cannot cross-compile to Apple targets without the macOS SDK, which Xcode's licence does not allow shipping into a shared CI image.

Building from source takes one command and no Xcode project — see below. It works the same on Apple Silicon and Intel.

Requirements

• Rust ≥ 1.95. The underlying oxihipo crate declares rust-version = "1.95", and CI builds on exactly that, so it is the real floor — higher than edition 2024's own minimum. Check with:

  rustc --version

  Update with rustup if needed (rustup update).

• A C compiler (default build only). By default oxihipo pulls the C LZ4 bindings (lz4-sys) for speed, which need a C toolchain (cc, clang, or MSVC). See pure-Rust build to avoid this.

Build from source

Clone the repository and build a release binary:

git clone git@code.jlab.org:hallb/clas12/hipoq.git
cd hipoq
cargo build --release

The binary is written to target/release/hipoq. Run it directly, or put it on your PATH:

./target/release/hipoq --help

# optional: install into ~/.cargo/bin
cargo install --path .

Once installed, the command is simply hipoq.

The command used to be hipo

It was renamed to match the project, and to stop competing for a name that already means three other things in this ecosystem: the file format, the C++ library (hipo4), and the hipo environment module on the JLab farm.

Nothing else changed — same subcommands, same flags, same output. If you have scripts calling the old name, either update them or add an alias:

alias hipo=hipoq

Faster allocation — --features mimalloc

Building from source uses the system allocator. On macOS, and on any static musl build, that is markedly slower under heavy allocation churn:

cargo build --release --features mimalloc

The published Linux binaries already have it. It is worth enabling for a source build on macOS, where the system allocator underperforms in the same way musl's does.

Pure-Rust build

On a machine without a C compiler, build the pure-Rust LZ4 path instead:

cargo build --release --no-default-features

If the linker still complains about lz4-sys, disable oxihipo's default features in Cargo.toml as well:

oxihipo = { git = "https://github.com/mathieuouillon/oxihipo", default-features = false }

Verify

Point it at any HIPO file:

hipoq info some_run.hipo

You should see the event count, record count, schema count, and per-file sizes. If you don't have a file handy, Get test data just below shows how to make one.

Get test data

The repository ships example generators (under examples/) that write small HIPO files you can experiment with:

# a CLAS12-shaped file: REC::Particle + REC::Calorimeter (with pindex) + REC::Event
cargo run --release --example gen_clas12 -- testdata/clas12.hipo

# a reconstruction-vs-truth file: MC::Particle + REC::Particle + MC::GenMatch
cargo run --release --example gen_mc -- testdata/mc.hipo

# the same, but with two truth particles close enough that geometry pairs them
# the WRONG way round while MC::GenMatch pairs them correctly — the case that
# is why `mc` has no geometric fallback
cargo run --release --example gen_truth -- testdata/truth.hipo

These are the fixtures the examples throughout this documentation use.