Table of Contents

• ESPP Library
  • Description
  • Installing the python package with pip
  • Building for PC (C++ & Python)
  • Updating the python bindings
    • Setup
    • Generating python bindings

This folder contains the configuration needed to cross-compile the central (cross-platform) components of espp for the following platforms:

• PC (Linux, MacOS, Windows)
  • C++
  • Python (through pybind 11)

Not all components of espp are cross-platform, so this library only references the cross-platform components of espp. The cross-platform components are those which do not depend on any specific hardware or platform.

Note: some components could be cross platform (e.g. various peripheral drivers and such), but are not currently exposed via this library.

Some examples can be found in these folders:

• ../pc: This folder contains c++ various example code which uses the espp library.
• ../python: This folder contains python code which uses the espp library.

All the examples in these folders require that the espp library is either installed via pip or built first, as described below.

The python bindings are packaged as the espp package on PyPI (see README_PYPI.md), built via scikit-build-core from the pyproject.toml at the repository root:

pip install espp

You can also install straight from git (requires CMake >= 3.21 and a C++23 compiler; pip clones the needed submodules automatically):

pip install git+https://github.com/esp-cpp/espp.git

When developing the bindings (or running the ../python example scripts against local changes), use an editable install from the repository root:

pip install -e .

Re-run it after changing C++ code to rebuild the extension (the CMake build dir is persistent, so rebuilds are incremental); pure-python changes are picked up automatically.

Wheels for Linux (x86_64 / aarch64), macOS (universal2), and Windows (amd64) are built in CI by build_wheels.yml and published to PyPI on each release.

To build the library for use on PC (with C++ and Python), install it into a staging prefix with cmake:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DESPP_INSTALL=ON -DESPP_BUILD_PYTHON=ON \
  -DCMAKE_INSTALL_PREFIX=../install
cmake --build build --config Release --target install --parallel 4

This is conveniently scripted up for you into ./build.sh and ./build.ps1 scripts you can simply run from your terminal; they install into <repo>/install.

This installs a standard, relocatable CMake package plus the python package into the prefix:

• <prefix>/lib/libespp_pc.a - C++ static library.
• <prefix>/include/ - all the header files needed to use the library from C++.
• <prefix>/lib/cmake/espp/ - esppConfig.cmake + friends, so another project can find_package(espp) and link the espp::espp target (see below).
• <prefix>/espp/ - the espp python package (pure-python files, type stubs, and the compiled espp._espp pybind11 extension) - add <prefix> to your PYTHONPATH / sys.path to import espp from python code.

The package version is derived from the latest git tag at configure time (a leading v is stripped), and falls back to 0.0.0 for tarball / no-git builds. The python wheel's version comes separately from setuptools_scm.

Point CMAKE_PREFIX_PATH at the install prefix and link the espp::espp target - it carries the include dirs, the C++23 requirement, and the PUBLIC system libraries, so nothing else is needed:

find_package(espp REQUIRED)
target_link_libraries(my_app PRIVATE espp::espp)
# If your app relies on espp's global-ctor / registration code (e.g. the Windows
# timer-period adjustment), whole-archive it (CMake 3.24+):
#   target_link_libraries(my_app PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,espp::espp>")

cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/install

The same espp::espp target is also available without installing, via FetchContent or CPM (build-tree consumers get the component headers directly). Both recurse espp's vendored third-party submodules (fmt, magic_enum, alpaca, cli, csv2, hid-rp, cdr, ...) for you, so no extra submodule step is needed:

# FetchContent
include(FetchContent)
FetchContent_Declare(espp
  GIT_REPOSITORY https://github.com/esp-cpp/espp.git
  GIT_TAG main
  SOURCE_SUBDIR lib)          # the C++ library lives in lib/
FetchContent_MakeAvailable(espp)
target_link_libraries(my_app PRIVATE espp::espp)

# CPM (https://github.com/cpm-cmake/CPM.cmake); after include(cmake/CPM.cmake)
CPMAddPackage(
  NAME espp
  GITHUB_REPOSITORY esp-cpp/espp
  GIT_TAG main
  SOURCE_SUBDIR lib)          # the C++ library lives in lib/
target_link_libraries(my_app PRIVATE espp::espp)

All three consumption paths (find_package, FetchContent, CPM) are exercised in CI by cmake_consumer.yml against the tests/consumer smoke project. The ../pc example tests consume the installed package via find_package.

You should only need to regenerate / update the python bindings if the espp code itself changes, and only if the changed code is exposed via this cross-platform library - meaning it's part of the ./include/espp.hpp or otherwise pointed to by espp.cmake.

We use litgen to automatically parse specific header files and generate python bindings for them in c++ using pybind11.

Relevant files:

• ./autogenerate_bindings.py: This is the script which configures litgen and generates the appropriate code. Inside this script is where we tell litgen which header files to generate python bindings for. Note that the ordering of the header file list is important.
• ./python_bindings/pybind_espp.cpp: This is where the generated pybind11 c++ code will go. It will need to be modified after generation (see below).

Create a virtual environment, and install the required packages:

python3 -m venv env
source env/bin/activate
pip install -r requirements.txt

# start the environment
source env/bin/activate
python autogenerate_bindings.py

No manual editing of the generated file is required, and no build/compile step is needed to fix it. autogenerate_bindings.py strips C++20 requires-clauses at parse time (so Vector2d and friends parse), then post-processes the generated pybind_espp.cpp entirely with static string/regex passes (_postprocess_generated) to fix every litgen/srcmlcpp bug that used to be fixed by hand:

• bogus implicit default constructors (Logger, Task, the RTSP packetizers, ...),
• template-class nested args (RangeMapper<int>, Bezier<espp::Vector2f>, Vector2d<float>),
• static/instance method duplicates (Task::get_id),
• std::shared_ptr holders + bases (the RTP packetizer hierarchy, JpegFrame),
• unqualified RTSP nested types / nested-struct statics in named-ctor defaults (espp::RtspClient::frame_callback_t, espp::RtspServer::Config::default_*, ...),
• def_readwrite → def_readonly for non-copyable members (RtspSession::Track sockets),
• py::call_guard<py::gil_scoped_release>() on blocking methods (Task::stop, Timer::cancel, socket send/receive/accept, the RTSP request methods, ...). Without it, any method that joins the task thread or blocks on I/O deadlocks when called from python, because the blocked-on thread needs the GIL to invoke its python callback (see _GIL_RELEASE_METHODS in autogenerate_bindings.py; the hand-written rtps bindings apply the same guard).

The litgen dependency is unpinned and recent versions (0.20–0.22) regressed nested-scope/template generation, which is why this automation is needed.

fix_generated_bindings.py is kept only as an optional diagnostic: if a future litgen version introduces new unqualified names, configure the build with cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S . -B build and run it — it compiles the generated file and reports clang's 'Y'; did you mean 'espp::X::Y'? suggestions so you can extend the static maps in autogenerate_bindings.py.

cdr and rtps are not generated by litgen — they are bound by hand in ./python_bindings/cdr_bindings.cpp and ./python_bindings/rtps_bindings.cpp (registered via py_init_cdr / py_init_rtps in module.cpp). litgen cannot bind them usefully (output-reference reads, non-owning std::span, std::function callbacks), and the hand-written shims give a clean, GIL-correct Python API (CdrWriter/CdrReader, RtpsParticipant with publish(topic, bytes) and ReaderConfig.on_sample = callable(bytes)). Edit those files directly; regeneration never touches them.