xo-reader2/README.md

Introduction

Local nix build for xo libraries. Intended for local development work, with source in immediate subdirectories.

Features

• native c++
• deterministic simulation
• reflection
• python bindings

Getting Started

Nix shell (reproducible development environment)

If nix is available, can get several reproducible build environments.

Pick one for a session:

$ cd xo-umbrella2
$ nix-shell -A shell0  # just nix stdenv: make,gcc,bash etc.
$ nix-shell -A shell1  # stable environment
$ nix-shell -A shell2  # stable environment + emacs + lsp
$ nix-shell -A shell3  # stable environment + emacs + lsp + xorg/opengl/vulkan/imgui stack (wsl2-only)
$ nix-shell -A shell4  # wsl2-specific. like shell3, vkcube works (at least on WSL)
$ nix-shell -A shell5  # wsl2-specific. uses dxg driver for "hardware acceleration"
$ nix-shell -A shell   # (deprecated) bleeding edge environment

Run emacs (for example) from within chosen seesion. We need this ordering because nix-shell determines vital details like location of shared libraries, including libraries used by running IDE.

$ emacs

Cmake build

If nix is available, you probably prefer the nix build. Otherwise continue reading..

The cmake build has two phases, because it needs to bootstrap generated xo-cmake-config, xo-build helpers.

$ cd xo
$ PREFIX=/path/to/say/usr/local
# phase 1
$ cmake -B .build0 -S xo-cmake -DCMAKE_INSTALL_PREFIX=${PREFIX}
$ cmake --build .build0
$ cmake --install .build0
# phase 2
$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=${PREFIX} -DXO_ENABLE_EXAMPLES=1
$ cmake --build .build --verbose
$ cmake --install .build

or with Vulkan examples

# at start of phase 2
$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=${PREFIX} -DXO_ENABLE_EXAMPLES=1 -DXO_ENABLE_VULKAN=1

Nix Build

Nix build uses toplevel default.nix, along with top-level pkgs/xo-foo.nix for each subproject foo. It doesn't interact with toplevel CMakeLists.txt.

$ nix-build -A xo-userenv

This builds all xo subprojects, assembles sandbox under ./result.

$ tree -L 1 ./result
./result
├── bin
│   ├── xo-build
│   ├── xo-cmake-config
│   └── xo-cmake-lcov-harness
└── share
    ├── cmake
    │   └── xo_macros
    │       ├── code-coverage.cmake
    │       ├── xo-project-macros.cmake
    │       └── xo_cxx.cmake
    ├── etc
    │   └── xo
    │       └── subsystem-list
    └── xo-macros
        ├── Doxyfile.in
        ├── gen-ccov.in
        └── xo-bootstrap-macros.cmake

For completeness' sake: can also use

$ nix-build -A xo-userenv-slow

Same result as $nix-build -A xo-userenv, but builds each package serially using xo-build.

Nix + Vulkan

Currently (Nov 2025) only affects xo-umbrella2/xo-imgui.

Non-trivial, because:

1. must use host OS for gpu drivers. nixpkgs has drivers, but they're setup to work from nixos.
2. want to use nixpkgs for the GPU-independent portion of graphics stack.

Complication because host gpu drivers in a "big swimming pool" such as /usr/lib/x86_64-linux-gnu/ that contains both libraries that must come from host OS (e.g. libGLX_nvidia) and libraries that must come from nixpkgs (e.g. libc)

Finesse by introducing a directory-of-symlinks, see xo-umbrella2/etc/{hostegl, hostubuntu}. These currently setup by hand, so likely to need manual attention on another host.

An ordinary cmake build may cheerfully use the host-provided graphics stack, in return for higher risk of DLL hell.

Coverage Build

Prepare build

# phase 2
$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=${PREFIX} -DCMAKE_BUILD_TYPE=coverage

Run coverage-enabled unit tests

$ (cd .build && ctest)

Generate coverage report

$ .build/gen-ccov

Html report left in .build/ccov/html/index.html

To view docs from WSL

1. find wsl IP address

$ hostname -I

2. run nix build

$ nix-build -A xo-userenv

3. serve docs from some available port

$ (cd result && python3 -m http.server 3000)

4. browse to ":3000/share/doc/xo-flatstring/html" from windows

To add a new satellite repo

1. check clone in clean state (all local changes committed or unwound)

2. add satellite as remote

$ git remote add xo-foo git@github.com:Rconybea/xo-foo.git
$ git fetch xo-foo

3. checkout satellite repo

$ git subtree add --prefix=xo-foo xo-foo main