Compilation and Installation

Minion can be used in two ways:

as the Python package minionpy;
as a native C++ library linked from another C++ project.

For Python users, start with the PyPI package. If a wheel is not available for your platform or Python version, build the Python interface from source. For C++ users, use a release package when available, or build the native library with CMake.

Python Package

Install MinionPy from PyPI:

python -m pip install --upgrade minionpy

Check the installation:

python -c "import minionpy; print(minionpy.__version__)"

PyPI wheels are not available for every operating system, Python version, or CPU architecture. If pip cannot find a compatible wheel, use Build MinionPy From Source.

Released Native Packages

To use an installed native C++ package from your own CMake project, make sure Eigen3 is also installed and discoverable by CMake.

On Ubuntu:

sudo apt update
sudo apt install libeigen3-dev

Linux users can install the native .deb package from the GitHub release assets:

sudo dpkg -i minion_<version>_<arch>.deb
sudo apt-get install -f

macOS users can install the native C++ package from the .tar.gz archive published in the GitHub release assets. Choose the archive that matches your machine:

Apple Silicon: minion-<version>-macos-arm64.tar.gz
Intel: minion-<version>-macos-x64.tar.gz

These archives are generated by CPack in CI.

On macOS with Homebrew:

brew install eigen

On macOS, Safari may automatically extract a downloaded .tar.gz archive. If that happens, use the extracted folder directly instead of running tar again, or disable Safari’s Open "safe" files after downloading setting.

Install into a user-local prefix such as $HOME/.local/minion:

mkdir -p /tmp/minion_pkg "$HOME/.local/minion"
tar -xzf minion-<version>-macos-<arch>.tar.gz -C /tmp/minion_pkg
ditto /tmp/minion_pkg/minion-<version>-macos-<arch> "$HOME/.local/minion"

This native package installs headers, shared libraries, CMake package files, and the CEC input-data directory. It does not install the Python package minionpy.

Because the macOS package is unsigned, Gatekeeper may block the installed libraries the first time you use them. If that happens, remove the quarantine attribute from the local install:

xattr -dr com.apple.quarantine "$HOME/.local/minion"

To let CMake find this local installation, add the prefix to CMAKE_PREFIX_PATH when configuring your project.

For example:

cmake -S . -B build -DCMAKE_PREFIX_PATH="$HOME/.local/minion"

On Apple Silicon with Homebrew Eigen3, you may need to include the Homebrew prefix as well:

cmake -S . -B build -DCMAKE_PREFIX_PATH="$HOME/.local/minion;/opt/homebrew"

If you use this installation often, you can also make the setting persistent in your shell profile, for example in ~/.zshrc or ~/.bashrc:

export CMAKE_PREFIX_PATH="$HOME/.local/minion:$CMAKE_PREFIX_PATH"

Windows users should build from source with CMake.

Source Build Requirements

Required for native C++ builds:

Git, when cloning the repository;
CMake >= 3.18;
a C++17 compiler, such as GCC, Clang, or MSVC;
Eigen3, or network access so CMake can fetch Eigen automatically.

Required for Python builds, including the default helper-script builds:

Python 3.9 or newer;
Python development headers;
pybind11.

Optional for documentation builds:

Doxygen;
Pandoc;
Sphinx;
sphinx-rtd-theme;
nbsphinx;
Breathe.

On Ubuntu 24.04, install the native build tools with:

sudo apt update
sudo apt install git cmake build-essential

For Python builds on Ubuntu 24.04, also install:

sudo apt install python3-dev python3-pip python3-pybind11

For documentation builds on Ubuntu 24.04, also install:

sudo apt install doxygen pandoc python3-sphinx python3-sphinx-rtd-theme \
  python3-nbsphinx python3-breathe

Clone the repository:

git clone https://github.com/khoirulmuzakka/Minion.git
cd Minion

Build From Source With CMake

Helper Scripts

The helper scripts build the C++ libraries, C++ examples, and Python extension module:

Linux/macOS: ./compile.sh
Windows: compile.bat

They configure CMake with:

MINION_BUILD_CEC=ON
MINION_BUILD_EXAMPLES=ON
MINION_BUILD_PYTHON=ON

Because Python bindings are enabled by default in the helper scripts, Python development headers and pybind11 must be available. To build only the native C++ library, use the manual CMake build below with MINION_BUILD_PYTHON=OFF.

Alternatively, edit compile.sh or compile.bat before running them and set the CMake options to match the build you want.

On Linux/macOS:

./compile.sh

For a debug build:

./compile.sh --debug

On Windows, run from a Developer Command Prompt or another shell where CMake and Visual Studio 2022 are available:

compile.bat

The helper scripts also try to build the documentation after compiling the project. If Doxygen, Pandoc, or one of the required Python documentation packages is missing, documentation generation is skipped with a warning. If all documentation tools are installed, the Sphinx build imports minionpy from the build tree.

Manual Native-Only CMake Build

For a native C++ build without Python bindings:

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DMINION_BUILD_CEC=ON \
  -DMINION_BUILD_PYTHON=OFF \
  -DMINION_BUILD_EXAMPLES=ON
cmake --build build --config Release

Install to a chosen prefix:

cmake --install build --prefix /path/to/minion-install

If Eigen3 is not installed, CMake fetches Eigen automatically by default. To require a system Eigen installation instead, add:

-DMINION_FETCH_EIGEN=OFF

Build MinionPy From Source

Use this route when no PyPI wheel is available for your platform, or when you want to use the Python interface from a local checkout.

Building MinionPy from source is the same CMake build as the native library, but with MINION_BUILD_PYTHON=ON:

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DMINION_BUILD_CEC=ON \
  -DMINION_BUILD_PYTHON=ON \
  -DMINION_BUILD_EXAMPLES=OFF
cmake --build build --config Release

The Python package code is in the minionpy directory. The compiled Python extension is written to minionpy/lib. After the build, import MinionPy from the repository root:

import minionpy
print(minionpy.__version__)

If you run Python from another directory, add the repository root (the parent directory of minionpy) to sys.path before importing minionpy:

import sys
sys.path.insert(0, "/path/to/Minion")

import minionpy
print(minionpy.__version__)

To select a specific Python interpreter, pass it to CMake:

cmake -S . -B build \
  -DMINION_BUILD_PYTHON=ON \
  -DPython3_EXECUTABLE=/path/to/python3

Make sure the python command on PATH belongs to the same environment and can import pybind11.

Build the Documentation

The documentation uses Doxygen for C++ API extraction and Sphinx for HTML pages. The Sphinx configuration imports minionpy, so build MinionPy first:

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DMINION_BUILD_CEC=ON \
  -DMINION_BUILD_PYTHON=ON
cmake --build build --config Release
doxygen Doxyfile
cd docs
make html

The generated HTML documentation is written to docs/build/html. On Windows, use docs\\make.bat html if GNU Make is not available.

Use Minion in a C++ Project

Include the main header:

#include <minion/minion.h>

Use find_package for an installed Minion package, with FetchContent as a fallback:

cmake_minimum_required(VERSION 3.18)
project(MyApp LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent)

find_package(Minion QUIET CONFIG)
if(NOT Minion_FOUND)
  FetchContent_Declare(
    minion
    GIT_REPOSITORY https://github.com/khoirulmuzakka/Minion.git
    GIT_TAG main
    GIT_SHALLOW TRUE
  )
  set(MINION_BUILD_CEC ON CACHE BOOL "Build CEC library" FORCE)
  set(MINION_BUILD_PYTHON OFF CACHE BOOL "Disable Python extension" FORCE)
  set(MINION_BUILD_EXAMPLES OFF CACHE BOOL "Disable examples" FORCE)
  FetchContent_MakeAvailable(minion)
endif()

add_executable(my_app src/main.cpp)
target_link_libraries(my_app PRIVATE minion)
# Optional: only if you use the CEC benchmark suite
# target_link_libraries(my_app PRIVATE minion_cec)