Skip to content

Installation Guide for punkst

This guide covers prebuilt Linux tarballs and source builds on Linux and macOS, including systems where you do not have root access.

Prebuilt Linux Tarballs

Prebuilt Linux tarballs are intended for linux users who want to run punkst without compiling from source. They are attached to GitHub Releases: https://github.com/Yichen-Si/punkst/releases

(You would still need to clone the repository get example data and workflow templates)

Choosing the Right Build

To get reasonable performance out of punkst, choose the tarball that best matches your system's Linux environment (glibc) and CPU capabilities.

Note: the tarball includes a built-in ./bin/env-check script. If you download a version your system doesn't support, the script should safely catch it and tell you which version to download instead

  1. Check your glibc version 
    ldd --version
  2. If your version is 2.28 or higher (e.g., Ubuntu 20.04+, RHEL 8+): Download a glibc2.28 tarball.

  3. If your version is 2.17 to 2.27 (e.g., CentOS 7, Ubuntu 18.04): Download a glibc2.17 tarball.

  4. Check your CPU (hardware capabilities)

grep -q avx512f /proc/cpuinfo && echo "x86_64-v4" || (grep -q avx2 /proc/cpuinfo && echo "x86_64-v3" || echo "x86_64")
  • x86_64-v4: Modern enterprise CPUs (Intel Skylake-X/Xeon or newer, AMD Zen 4 or newer, with AVX-512 support)
  • x86_64-v3: Most standard CPUs made after 2015 (Intel Haswell+, AMD Zen 1-3)
  • x86_64: Older CPUs or lightweight VMs

The performance difference may be significant, mostly due to optimizations inside Eigen. It is important to choose the matching prebuilt tarball.

Note: on HPC, you may need to check the features of the compute node. For example, with slurm scheduler you can do srun -p <PARTITION> bash -c 'ldd --version | head -n 1' and srun -p <PARTITION> bash -c 'echo -n "$(hostname): " && (grep -q avx512f /proc/cpuinfo && echo "x86_64-v4" || (grep -q avx2 /proc/cpuinfo && echo "x86_64-v3" || echo "x86_64"))'

After downloading

tar -xzf punkst-*-linux-x86_64*-glibc*.tar.gz
cd punkst-*-linux-x86_64*-glibc*
./bin/env-check

bin/env-check is a shell helper that checks the host glibc version and CPU features before launching bin/punkst with the bundled libraries. If checks pass, it shows the punkst help message, then the binary ./bin/punkst is ready to use.

The tarball includes Markdown documentation under docs/. The latest documentation is available online at https://yichen-si.github.io/punkst/.

Building from Source

Requirements

Core build requirements:

  • Git
  • CMake >= 3.15
  • C++17 compiler*
  • TBB
  • zlib
  • BZip2
  • LibLZMA

Optional feature requirements:

  • libpng: needed only when ENABLE_IMAGE_OUTPUT=ON, which is the default
  • libcurl: needed only when ENABLE_REMOTE_IO=ON, which is the default

*GCC 9 or newer is the supported Linux baseline. GCC 8 may work in some environments, but older std::filesystem support varies across distributions. Clang, Apple Clang, and MSVC need C++17 standard library support.

Image output commands write PNG files and require output paths ending in .png.

Quick Build

git clone --recursive https://github.com/your-org/punkst.git
cd punkst

mkdir build
cd build
cmake ..
cmake --build . --parallel

For single-config generators such as Unix Makefiles and Ninja, cmake .. defaults to a Release build to prioritize runtime performance.

If the repository was cloned without submodules, initialize them before configuring:

git submodule update --init

The punkst binary is placed in bin/ under the project root.

Verify the build:

../bin/punkst --help

You should see a message starting with:

Available Commands
The following commands are available:

System Packages

Install dependencies with your system package manager when possible:

Library Ubuntu / Debian CentOS / RHEL macOS Homebrew
TBB sudo apt-get install libtbb-dev sudo yum install tbb-devel brew install tbb
zlib sudo apt-get install zlib1g-dev sudo yum install zlib-devel brew install zlib
BZip2 sudo apt-get install libbz2-dev sudo yum install bzip2-devel brew install bzip2
LibLZMA sudo apt-get install liblzma-dev sudo yum install xz-devel brew install xz
libpng sudo apt-get install libpng-dev sudo yum install libpng-devel brew install libpng
libcurl sudo apt-get install libcurl4-openssl-dev sudo yum install libcurl-devel brew install curl

Rootless Installs

If dependencies are installed under a user prefix, pass that prefix to CMake:

cmake .. \
  -DTBB_DIR="$HOME/.local/lib/cmake/tbb" \
  -DCMAKE_PREFIX_PATH="$HOME/.local"

TBB

For TBB, see oneTBB installation guide

Install from released packages: 

wget https://github.com/uxlfoundation/oneTBB/releases/download/v2023.0.0/oneapi-tbb-2023.0.0-lin.tgz
tar -zxvf oneapi-tbb-2023.0.0-lin.tgz
Then do the following (everytime) before you build punkst 
source oneapi-tbb-2023.0.0/env/vars.sh

libpng

For libpng without root access, use a user-level package manager when available:

# conda/mamba
conda install -c conda-forge libpng zlib
cmake .. -DCMAKE_PREFIX_PATH="$CONDA_PREFIX"

# spack
spack install libpng
spack load libpng
cmake .. -DCMAKE_PREFIX_PATH="$(spack location -i libpng)"

If package managers are unavailable, libpng can be built from source into a user prefix. Build zlib locally first as well if the system zlib development files are unavailable.

cmake -S /path/to/libpng -B /path/to/libpng/build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build /path/to/libpng/build --parallel
cmake --install /path/to/libpng/build

cmake .. -DCMAKE_PREFIX_PATH="$HOME/.local"

Optional Features

Image output is enabled by default:

cmake .. -DENABLE_IMAGE_OUTPUT=ON

This builds:

  • draw-pixel-factors
  • draw-lowres-factors
  • draw-pixel-features

Disable image output to build without libpng:

cmake .. -DENABLE_IMAGE_OUTPUT=OFF

Remote random-access readers for http(s) and s3:// inputs are enabled by default:

cmake .. -DENABLE_REMOTE_IO=ON

Disable remote I/O to build without libcurl. Local-file input still works.

cmake .. -DENABLE_REMOTE_IO=OFF

Performance And Portability

The default build prioritizes local runtime performance:

  • CMAKE_BUILD_TYPE=Release when no build type is specified
  • ENABLE_LTO=ON
  • ENABLE_NATIVE_ARCH=ON

Useful CMake options:

Goal CMake command Description
Default local performance cmake .. Release build with -march=native when supported
Maximum CPU portability cmake .. -DENABLE_PORTABLE_BUILD=ON Disables architecture-specific tuning flags
Modern x86_64 baseline cmake .. -DENABLE_NATIVE_ARCH=OFF -DENABLE_X86_64_V3=ON Targets x86-64-v3 on compatible x86_64 systems
AVX-512 x86_64 target cmake .. -DENABLE_NATIVE_ARCH=OFF -DENABLE_X86_64_V4=ON Targets x86-64-v4 on compatible AVX-512 systems
Disable LTO cmake .. -DENABLE_LTO=OFF Useful for faster/debug builds or toolchains where LTO is unreliable
No image output cmake .. -DENABLE_IMAGE_OUTPUT=OFF Builds without libpng
No remote I/O cmake .. -DENABLE_REMOTE_IO=OFF Builds without libcurl