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.