183 lines
4.4 KiB
Markdown
183 lines
4.4 KiB
Markdown
# 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 "<wsl-ip-address>: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
|
|
```
|