xo-umbrella2: correct indentlog makefile doc target + misc doc ++
This commit is contained in:
parent
f4c35c4d3f
commit
07b6cc949f
3 changed files with 111 additions and 21 deletions
|
|
@ -124,6 +124,6 @@ add_subdirectory(xo-imgui)
|
|||
# ----------------------------------------------------------------
|
||||
# documentation. must follow add_subdirectory() for satellite projects
|
||||
|
||||
xo_umbrella_doxygen_deps(xo_alloc xo_indentlog xo_flatstring xo_ratio xo_unit xo_tokenizer xo_reader xo_jit)
|
||||
xo_umbrella_doxygen_deps(xo_alloc indentlog xo_flatstring xo_ratio xo_unit xo_tokenizer xo_reader xo_jit)
|
||||
xo_umbrella_doxygen_config()
|
||||
xo_umbrella_sphinx_config(index.rst docs/install.rst docs/glossary.rst)
|
||||
|
|
|
|||
76
README.md
76
README.md
|
|
@ -12,6 +12,8 @@ Intended for local development work, with source in immediate subdirectories.
|
|||
|
||||
## 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.
|
||||
|
|
@ -37,9 +39,12 @@ 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.
|
||||
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
|
||||
|
|
@ -53,7 +58,7 @@ $ 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 -DCMAKE_BUILD_TYPE=debug
|
||||
$ 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
|
||||
```
|
||||
|
|
@ -64,6 +69,37 @@ or with Vulkan examples
|
|||
$ 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
|
||||
|
||||
|
|
@ -107,11 +143,19 @@ $ nix-build -A xo-userenv-slow
|
|||
Same result as `$nix-build -A xo-userenv`, but builds each package serially
|
||||
using `xo-build`.
|
||||
|
||||
#### Nix + Vulkan
|
||||
#### Nix + SDL2 + Vulkan + ImGui
|
||||
|
||||
Currently (Nov 2025) only affects `xo-umbrella2/xo-imgui`.
|
||||
|
||||
Non-trivial, because:
|
||||
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.
|
||||
|
||||
|
|
@ -125,25 +169,23 @@ These currently setup by hand, so likely to need manual attention on another hos
|
|||
An ordinary cmake build may cheerfully use the host-provided graphics stack,
|
||||
in return for higher risk of DLL hell.
|
||||
|
||||
### Coverage Build
|
||||
|
||||
Prepare build
|
||||
To build for ubuntu with nvidia gpu:
|
||||
```
|
||||
# phase 2
|
||||
$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=${PREFIX} -DCMAKE_BUILD_TYPE=coverage
|
||||
$ 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
|
||||
```
|
||||
|
||||
Run coverage-enabled unit tests
|
||||
To build for wsl:
|
||||
```
|
||||
$ (cd .build && ctest)
|
||||
$ 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
|
||||
```
|
||||
|
||||
Generate coverage report
|
||||
```
|
||||
$ .build/gen-ccov
|
||||
```
|
||||
|
||||
Html report left in ``.build/ccov/html/index.html``
|
||||
Currently not supporting a nix sandbox build for xo-imgui
|
||||
|
||||
## To view docs from WSL
|
||||
|
||||
|
|
|
|||
|
|
@ -61,10 +61,15 @@ The first phase bootstraps some generated helper scripts used in the second phas
|
|||
$ cmake --install .build0
|
||||
|
||||
# phase 2 -- build XO, using helpers installed in phase 1.
|
||||
$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=$PREFIX
|
||||
|
||||
# -DXO_ENABLE_DOCS=1 : builds documentation; or 0 to skip
|
||||
# -DXO_ENABLE_EXAMPLES=1 : builds example; or 0 to skipos
|
||||
# -DXO_ENABLE_VULKAN=1 : builds vulkan-dependent graphics pipeline for imgui; or 0 to skip
|
||||
|
||||
$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=$PREFIX -DXO_ENABLE_DOCS=1 -DXO_ENABLE_EXAMPLES=1 -DXO_ENABLE_VULKAN=1
|
||||
$ cmake --build .build -j
|
||||
|
||||
# optionally build docs
|
||||
# optionally build docs (requires -DXO_ENABLE_DOCS in phase2 config)
|
||||
$ cmake --build .build -- docs
|
||||
|
||||
$ cmake --install .build
|
||||
|
|
@ -100,6 +105,50 @@ See ``Test Coverage Setup`` under ``Development`` below
|
|||
Development
|
||||
===========
|
||||
|
||||
Environment
|
||||
-----------
|
||||
|
||||
If nix is available, can use `nix-shell` to get a reproducible development environment for XO work.
|
||||
Run `nix-shell` from the top-level `xo-umbrella2` directory.
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 20 60 30
|
||||
|
||||
* - command
|
||||
- sufficient for
|
||||
- platform
|
||||
* - `nix-shell -A shell1a`
|
||||
- `cmake -DXO_ENABLE_DOCS=0 -DXO_ENABLE_OPENGL=0 -DXO_ENABLE_VULKAN=0`
|
||||
-
|
||||
* - `nix-shell -A shell1`
|
||||
- `cmake -DXO_ENABLE_DOCS=1`
|
||||
-
|
||||
* - `nix-shell -A shell3`
|
||||
- `cmake -DXO_ENABLE_OPENGL=1`
|
||||
-
|
||||
* - `nix-shell -A shell4-wsl`
|
||||
- `cmake -DXO_ENABLE_VULKAN=1`
|
||||
- wsl2 on windows11
|
||||
* - `nix-shell -A shell4-nvidia`
|
||||
- `cmake -DXO_ENABLE_VULKAN=1`
|
||||
- nvidia GPU on linux
|
||||
* - `nix-shell -A shell4-osx`
|
||||
- `cmake -DXO_ENABLE_VULKAN=1`
|
||||
- mac osx
|
||||
|
||||
For example
|
||||
|
||||
.. code-block::
|
||||
|
||||
$ cd xo-umbrella2
|
||||
$ nix-shell -A shell4-nvidia
|
||||
$ echo $VK_ICD_FILENAMES
|
||||
/usr/share/vulkan/icd.d/nvidia_icd.json # point to library to use for nvidia gpu on this host
|
||||
$ which doxygen
|
||||
/home/roland/nixroot/nix/store/cb78mifxvic291rcb2qlbpxgl29f5pzf-doxygen-1.13.2/bin/doxygen
|
||||
# etc.
|
||||
|
||||
LSP Setup
|
||||
---------
|
||||
|
||||
|
|
@ -137,7 +186,6 @@ To build coverage report
|
|||
Html report in ``.build/ccov/html/index.html``
|
||||
|
||||
|
||||
|
||||
Sphinx Autobuild Setup
|
||||
----------------------
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue