pocketpy/docs/build.md

---

icon: tools order: 19

label: Build Configuration

Build configuration

Quick start covers the default build. This page explains the options that change what the interpreter can do.

CMake options

Pass options when configuring the build:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DPK_BUILD_STATIC_MAIN=ON -DPK_BUILD_MODULE_LZ4=ON
cmake --build build --config Release

When embedding with add_subdirectory(pocketpy), set cache options before adding the subdirectory, or pass them on the CMake command line.

Option	Default	Effect
PK_BUILD_SHARED_LIB	OFF	Build only the shared library.
PK_BUILD_STATIC_LIB	OFF at the repository root; ON as a dependency	Build only the static library.
PK_BUILD_STATIC_MAIN	OFF	Link the standalone executable statically when neither library-only option is selected.
PK_BUILD_WITH_UNITY	ON	Combine interpreter sources into a unity build.
PK_ENABLE_OS	ON	Enable host OS facilities, including file access and the default debugger transport.
PK_ENABLE_THREADS	ON	Enable thread support and pkpy.ComputeThread.
PK_ENABLE_DLL	ON	Enable native dynamic-module loading on supported desktop platforms.
PK_ENABLE_DETERMINISM	ON	Use the project's deterministic math implementation.
PK_ENABLE_WATCHDOG	OFF	Enable execution timeout checks.
PK_ENABLE_CUSTOM_SNAME	OFF	Omit the built-in name implementation; an advanced host integration must supply its own.
PK_ENABLE_MIMALLOC	OFF	Fetch and use mimalloc instead of the default allocator.

Select at most one library-only option. With both off, the root build creates the standalone main executable and a library.

The following modules are optional and default to OFF:

Option	Module
PK_BUILD_MODULE_LZ4	lz4
PK_BUILD_MODULE_CUTE_PNG	cute_png
PK_BUILD_MODULE_MSGPACK	msgpack
PK_BUILD_MODULE_PERIPHERY	periphery, for Linux hardware I/O

Initialize the required Git submodules before enabling a module that uses them:

git submodule update --init --recursive

The exact options are defined in CMakeOptions.txt.

Compiling without the project CMake target

Compile the interpreter as C11, even when your application uses C++. Use an optimized build with NDEBUG for deployment. For MSVC, include /utf-8 and /experimental:c11atomics.

The defaults in config.h differ from CMake: PK_ENABLE_THREADS, PK_ENABLE_DLL, and PK_ENABLE_DETERMINISM default to 0 unless explicitly enabled. Do not assume a manually compiled interpreter has the same features as a CMake build.

Match the platform libraries and feature definitions in CMakeLists.txt. For example, Windows uses ws2_32; enabled thread support needs the platform thread library, and supported Unix dynamic loading uses dl. Optional modules also need their native sources and libraries; defining a module macro alone is insufficient.

Inspect the running build

import pkpy

print(pkpy.configmacros)
print(pkpy.currentvm())  # 0 in the default VM

This is useful when a script runs on the desktop but a module or feature is unavailable in an embedded or browser build. Disabling OS access reduces the exposed facilities; it does not turn the interpreter into a security sandbox.