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:

.. code-block:: shell

   python -m pip install --upgrade minionpy

Check the installation:

.. code-block:: shell

   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:

.. code-block:: shell

   sudo apt update
   sudo apt install libeigen3-dev

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

.. code-block:: shell

   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:

.. code-block:: shell

   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``:

.. code-block:: shell

   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:

.. code-block:: shell

   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:

.. code-block:: shell

   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:

.. code-block:: shell

   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``:

.. code-block:: shell

   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:

.. code-block:: shell

   sudo apt update
   sudo apt install git cmake build-essential

For Python builds on Ubuntu 24.04, also install:

.. code-block:: shell

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

For documentation builds on Ubuntu 24.04, also install:

.. code-block:: shell

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

Clone the repository:

.. code-block:: shell

   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:

.. code-block:: shell

   ./compile.sh

For a debug build:

.. code-block:: shell

   ./compile.sh --debug

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

.. code-block:: bat

   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:

.. code-block:: shell

   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:

.. code-block:: shell

   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:

.. code-block:: shell

   -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``:

.. code-block:: shell

   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:

.. code-block:: python

   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``:

.. code-block:: python

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

   import minionpy
   print(minionpy.__version__)

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

.. code-block:: shell

   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:

.. code-block:: shell

   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:

.. code-block:: cpp

   #include <minion/minion.h>

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

.. code-block:: cmake

   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)