# Building from source

A source checkout is for working on SimVX itself. To make a game, {doc}`install` with pip.

## Set up a checkout

You need Python 3.14+, a Vulkan driver ({doc}`install`), [`uv`](https://docs.astral.sh/uv/) and
`glslc` (a checkout compiles the engine's shaders on first use; see
[Shader compiler](install.md#shader-compiler)).

```bash
git clone https://git.simvx.com/simvx/simvx.git
cd simvx
uv sync                     # every package, editable, plus the dev tools
uv sync --extra examples    # the example library, for `simvx examples`
```

Run everything from the repository root through `uv run`: a bare `python` or `pytest` does not
resolve the workspace packages.

```bash
uv run python examples/tutorials/pong/main.py
uv run --package simvx-core pytest packages/core/tests
```

Always give pytest a path. Without one it collects every package's suite at once.

## Dependency groups

| Group | Adds | Installed by |
|---|---|---|
| `dev` | pytest, ruff, mypy, and what the suites use beyond them | `uv sync` (the default group) |
| `docs` | Sphinx, MyST, autodoc2, sphinx-design, furo | `uv sync --group docs` |

## Native accelerators

`simvx-audio-miniaudio`, `simvx-textures-basis` and `simvx-physics-jolt` each build one shared
library, loaded through cffi. `uv sync` builds them with the zig compiler, which their build
requirements fetch from PyPI (with CMake and ninja for Jolt), so no system compiler is needed.

- **After editing C or C++ sources**, rebuild one package; an unchanged version is otherwise kept:

  ```bash
  uv sync --reinstall-package simvx-physics-jolt
  ```

- **Build parallelism.** The Jolt build runs a conservative number of compilers at a time, to fit
  a machine short of memory. Set `CMAKE_BUILD_PARALLEL_LEVEL` to run more.
- **Stale libraries.** cffi resolves each function on first use, so a library built from older
  glue loads and fails later with an `AttributeError`. Set `SIMVX_VALIDATE_NATIVE=1` to look up
  every declared function as the library opens; a missing one raises `ImportError` naming it. The
  test suites turn it on.

Each accelerator package has the same layout:

| Path | Holds |
|---|---|
| `src/simvx/<area>/<name>/` | the Python binding, with `_cdef.py` holding the cffi declarations |
| `src/simvx/<area>/<name>/glue/` | the C or C++ glue, whose header (`glue.h`, or `jolt_glue.h` for Jolt) repeats the `_cdef.py` declarations |
| `vendor/` | the upstream library, unmodified |
| `build_native_hook.py` | the build, through the shared tooling in `tools/native/` |

`tools/native/README.md` documents the build tooling and its tests.

## The example library

The examples are the `simvx-examples` distribution, and it has no editable install. After editing
anything under `examples/_package/`, reinstall it:

```bash
uv sync --extra examples --reinstall-package simvx-examples
```

`SIMVX_EXAMPLES_ROOT` points `simvx examples` at another tree, such as a checkout's `examples/`.

## Build the docs

```bash
uv run python tools/build_examples.py docs     # generates the examples gallery pages
uv run --with setuptools --group docs sphinx-build -j6 docs docs/_build/html
```

Then open `docs/_build/html/index.html`. The gallery pages are generated, not tracked, so the first
command runs before the second.

## Project structure

```
packages/
  core/             Backend-agnostic engine: nodes, signals, animation, audio, UI, physics, scene I/O
  graphics/         Vulkan renderer and windowing
  web/              Browser runtime and the `simvx export web` exporter
  editor/           Visual scene editor, built on simvx.core.ui
  ide/              Engine-native Python IDE (LSP, debugger, terminal)
  ai/               LLM layer
  audio-miniaudio/  Native audio accelerator (miniaudio)
  textures-basis/   Native UASTC texture transcoder (basis_universal)
  physics-jolt/     Native Jolt 3D physics backend, selected on request
examples/           Tutorials, feature references, demos and ports (the simvx-examples distribution)
docs/               Documentation site source
tools/              Build, test and docs tooling, including the native accelerator build
tests/              Repository-level tests that belong to no package
```

## Next steps

- [Contributing](https://git.simvx.com/simvx/simvx/src/branch/main/CONTRIBUTING.md): checks to run
  and how to send a change.
- [AGENTS.md](https://git.simvx.com/simvx/simvx/src/branch/main/AGENTS.md): engine rules and example
  conventions.
- [Performance suite](https://git.simvx.com/simvx/simvx/src/branch/main/tests/perf/README.md): the
  opt-in benchmarks.