restore README.md

2025-12-07 01:51:15 -05:00 · 2025-12-07 01:51:15 -05:00 · c1d33d71c5
commit c1d33d71c5
parent 5a9356edcc
1 changed files with 225 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -1 +1,225 @@
-# readme
+# 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
+
+(Alternatively, see `xo-umbrella2/docs/install.rst` for similar content)
+
+### 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
+```
+
+Can use `nix-shell` to get reproducible environment for cmake build, see `Cmake Build`.
+Alternatively can use full nix build, see `Nix Build`
+
+### Cmake build
+
+If `nix` is available, you probably prefer the nix build, unless working on XO itself.
+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 -DXO_ENABLE_DOCS=1 -DCMAKE_BUILD_TYPE=debug
+$ 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
+```
+
+### Cmake build documentation
+
+Documentation relies on doxygen, sphinx and breathe.
+```
+# phase 2
+$ cd xo-umbrella2
+$ cmake -B .build -S . -DXO_ENABLE_DOCS=1
+$ cmake --build .build -- docs
+```
+
+Create Html docs in `.build/sphinx/html/index.html`
+
+### Cmake build with coverage
+
+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``
+
+### 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 + SDL2 + Vulkan + ImGui
+
+Currently (Nov 2025) only affects `xo-umbrella2/xo-imgui`.
+
+For OSX, imgui works with assistance from motlenvk.
+Build `xo-imgui` with
+
+```
+$ cd xo-umbrella2
+$ nix-shell -A shell4-osx   # see xo-umrbella2/default.nix for impl
+```
+
+For linux and/or wsl build need extra care:
+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.
+
+To build for ubuntu with nvidia gpu:
+```
+$ cd xo-umbrella2
+$ nix-shell -A shell4-nvidia
+# then regular cmake:
+$ cmake -B .build -S . -DXO_ENABLE_VULKAN=1 -DXO_ENABLE_EXAMPLES=1 -DCMAKE_INSTALL_PREFIX=$PREFIX
+```
+
+To build for wsl:
+```
+$ cd xo-umbrella2
+$ nix-shell -A shell4-wsl
+# then regular cmake:
+$ cmake -B .build -S . -DXO_ENABLE_VULKAN=1 -DXO_ENABLE_EXAMPLES=1 -DCMAKE_INSTALL_PREFIX=$PREFIX
+```
+
+Currently not supporting a nix sandbox build for xo-imgui
+
+## 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 main
+```
+
+3. checkout satellite repo
+
+```
+$ git subtree add --prefix=xo-foo xo-foo main
+```