213 lines
4.7 KiB
ReStructuredText
213 lines
4.7 KiB
ReStructuredText
.. _install:
|
|
|
|
.. toctree
|
|
:maxdepth: 2
|
|
|
|
Source
|
|
======
|
|
|
|
Source code for XO is on github `here`_
|
|
|
|
.. _here: https://github.com/rconybea/xo-umbrella2
|
|
|
|
This repo contains source to all the XO libraries, in the most convenient form for
|
|
building + installing all XO libraries, or developing changes to XO itself.
|
|
|
|
Install
|
|
=======
|
|
|
|
This section explains how to build and install all XO libraries at once.
|
|
If you only want to install a subset of XO, refer to build instructions for individual subsystems.
|
|
You can build XO using cmake or nix.
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
XO dependencies (if you're using nix, it will assemble these for you)
|
|
|
|
- cmake
|
|
- llvm
|
|
- libwebsockets
|
|
- jsoncpp
|
|
- eigen
|
|
- catch2
|
|
- pybind11
|
|
|
|
XO documentation requires:
|
|
|
|
- doxygen
|
|
- graphviz
|
|
- sphinx
|
|
- sphinx-rtd-theme
|
|
- breathe
|
|
- sphinxcontrib-ditaa
|
|
- sphinxcontrib-plantuml
|
|
- pilllow
|
|
|
|
cmake build
|
|
-----------
|
|
|
|
The cmake build has two phases.
|
|
The first phase bootstraps some generated helper scripts used in the second phase.
|
|
|
|
.. code-block::
|
|
|
|
$ git clone https://github.com/rconybea/xo-umbrella2
|
|
$ cd xo-umbrella2
|
|
$ PREFIX=/usr/local # for example
|
|
|
|
# phase 1 -- install helper scripts
|
|
$ cmake -B .build0 -S xo-cmake -DCMAKE_INSTALL_PREFIX=$PREFIX
|
|
$ cmake --install .build0
|
|
|
|
# phase 2 -- build XO, using helpers installed in phase 1.
|
|
|
|
# -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 (requires -DXO_ENABLE_DOCS in phase2 config)
|
|
$ cmake --build .build -- docs
|
|
|
|
$ cmake --install .build
|
|
|
|
|
|
nix build
|
|
---------
|
|
|
|
Nix build uses toplevel ``default.nix``, along with ``pkgs/xo-foo.nix`` for each subsystem ``foo``.
|
|
It ignores toplevel ``CMakeLists.txt``
|
|
|
|
Build XO libraries, assemble sanbox under ``./result``
|
|
|
|
.. code-block::
|
|
|
|
$ nixbuild -A xo-userenv
|
|
|
|
|
|
Aternatively can enter nix environment, then follow instructions for cmake build:
|
|
|
|
.. code-block::
|
|
|
|
$ nix-shell
|
|
$ /nix/store/<hash>-doxygen-1.10.0/bin/doxygen
|
|
# etc
|
|
|
|
|
|
coverage build
|
|
--------------
|
|
|
|
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
|
|
---------
|
|
|
|
To setup xo-umbrella2 build to work with a language server:
|
|
|
|
.. code-block::
|
|
|
|
$ cd xo-umbrella2
|
|
$ ln -s .build /compile_commands.json # lsp will look for compile_commands.json in project root
|
|
|
|
|
|
In this case subsystem LSP setup should be omitted, git root is ``path/to/xo-umbrella2``,
|
|
not ``path/to/xo-umbrella2/xo-ratio`` etc.
|
|
|
|
Test Coverage Setup
|
|
-------------------
|
|
|
|
To setup a unit test coverage build/ccov/all-merged
|
|
|
|
.. code-block::
|
|
|
|
# can reuse phase 1 cmake-macros-install
|
|
|
|
# phase 2
|
|
$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=$PREFIX -DCMAKE_BUILD_TYPE=coverage
|
|
|
|
Then run unit tests
|
|
|
|
.. code-block::
|
|
|
|
$ (cd .build && ctest)
|
|
|
|
To build coverage report
|
|
|
|
.. code-block::
|
|
|
|
$ (.build/gen-ccov)
|
|
|
|
Html report in ``.build/ccov/html/index.html``
|
|
|
|
|
|
Address Sanitizer Setup
|
|
-----------------------
|
|
|
|
To run address sanitizer
|
|
|
|
.. code-block::
|
|
|
|
# can reuse phase 1 cmake-macros-install
|
|
|
|
# phase 2
|
|
$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=$PREFIX -DCMAKE_BUILD_TYPE=asan
|
|
|
|
Sphinx Autobuild Setup
|
|
----------------------
|
|
|
|
To serve cache-busting headers
|
|
|
|
.. code-block::
|
|
|
|
$ cd xo-umbrella2
|
|
$ sphinx-autobuild . .build/sphinx/html --port 3000
|