Build Guide¶

This guide covers building the Pytonium Python framework from source on Windows and Linux using CLI commands.

Prerequisites¶

sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build python3-dev python3-venv git binutils

Step 1: Clone the Repository¶

git clone https://github.com/Maximilian-Winter/pytonium.git
cd pytonium

Step 2: Set Up Python Environment¶

python -m venv .venv
.venv\Scripts\activate
pip install --upgrade pip
pip install build scikit-build cmake ninja Cython

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install build scikit-build cmake ninja Cython

Step 3: Build the C++ Subprocess¶

CEF uses a multi-process architecture and requires a separate pytonium_subprocess executable.

cmake -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-release --target pytonium_subprocess --config Release

cmake -B build_linux -DCMAKE_BUILD_TYPE=Release
cmake --build build_linux --target pytonium_subprocess

This also builds the pytonium_library and libcef_dll_wrapper dependencies automatically.

For more details on the subprocess, see the Subprocess Build page.

Step 4: Prepare Build Files¶

The prepare_build.py script syncs C++ sources, copies CEF binaries, and places the subprocess executable into the correct locations for the Python wheel build.

cd building_pythonium_core
python prepare_build.py --platform windows --build-dir ../cmake-build-release

cd building_pythonium_core
python3 prepare_build.py --platform linux --build-dir ../build_linux

The script performs the following steps:

1. Cleans old build artifacts (dist/, _skbuild/, Pytonium.egg-info/, bin_win/ or bin_linux/)
2. Syncs C++ library source files into the pyframework directory
3. Syncs subprocess source files
4. Copies CEF binaries (headers, cmake modules, libcef_dll wrapper, libcef)
5. Copies CEF runtime resources and shared libraries to the bin folder
6. Copies the pytonium_subprocess executable to the bin folder
7. On Linux: strips debug symbols from .so files (e.g., libcef.so 1.5 GB -> ~250 MB)

For the full options reference, see Prepare Build Script.

Step 5: Build the Wheel¶

cd ../src/pytonium_python_framework
python -m build --wheel

cd ../src/pytonium_python_framework
python3 -m build --wheel

This creates a wheel file in src/pytonium_python_framework/dist/, for example:

• Windows: pytonium-0.0.13-cp310-cp310-win_amd64.whl
• Linux: pytonium-0.0.13-cp310-cp310-linux_x86_64.whl

Step 6: Install the Package¶

pip install dist/pytonium-*.whl --force-reinstall

Quick Reference (Full Workflow)¶

git clone https://github.com/Maximilian-Winter/pytonium.git
cd pytonium
python -m venv .venv
.venv\Scripts\activate
pip install --upgrade pip build scikit-build cmake ninja Cython

cmake -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-release --target pytonium_subprocess --config Release

cd building_pythonium_core
python prepare_build.py --platform windows --build-dir ../cmake-build-release
cd ../src/pytonium_python_framework
python -m build --wheel
pip install dist/pytonium-*.whl --force-reinstall

git clone https://github.com/Maximilian-Winter/pytonium.git
cd pytonium
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip build scikit-build cmake ninja Cython

cmake -B build_linux -DCMAKE_BUILD_TYPE=Release
cmake --build build_linux --target pytonium_subprocess

cd building_pythonium_core
python3 prepare_build.py --platform linux --build-dir ../build_linux
cd ../src/pytonium_python_framework
python3 -m build --wheel
pip install dist/pytonium-*.whl --force-reinstall

Verification¶

from Pytonium import Pytonium

print("Pytonium imported successfully!")
p = Pytonium()
print("Pytonium instance created successfully!")

If both messages print without errors, your build is working.

Troubleshooting¶

"pytonium_subprocess not found at expected locations"¶

The subprocess executable has not been built, or was built to a non-standard directory.

"CMake Error: Could not find package configuration file provided by 'CEF'"¶

The CEF binary distribution is missing.

"libcef.so missing" or ninja error about missing .so file¶

On Linux, libcef.so (~1.5 GB) must be copied to bin_linux/ and then into the CEF build directory by setup.py. If prepare_build.py was not run (or was run with --skip-cef), this file will be missing.

Stale _skbuild cache causes FindCython or other CMake errors¶

The _skbuild/ directory caches CMake configuration between builds. If your build environment changes (e.g., different Python virtualenv, different temp paths), the cache becomes stale.

Build takes very long or hangs¶

• The first build compiles the CEF wrapper library (~200 source files). Subsequent builds are faster.
• Ensure at least 8 GB of free RAM.
• On WSL with NTFS mounts (/mnt/...), I/O is significantly slower than on native ext4.

Windows: "Syntaxfehler" or macro conflicts¶

Clean Build¶

To perform a completely clean build, re-run prepare_build.py without --skip-clean (the default). This removes _skbuild/, dist/, Pytonium.egg-info/, and the platform bin folder.

Alternatively, clean manually:

cd src/pytonium_python_framework
rm -rf _skbuild dist Pytonium.egg-info

See Also¶

• Subprocess Build -- Detailed subprocess build guide
• Prepare Build Script -- Full prepare_build.py reference
• Pytonium Examples -- Example applications