# Exudyn developer documentation

Developer-facing notes. Users start at [`README.rst`](https://github.com/jgerstmayr/EXUDYN/blob/master/README.rst) and
[`INSTALL.txt`](../../INSTALL.txt) in the repository root, or at the
[online documentation](https://exudyn.readthedocs.io/).

| document | contents |
|---|---|
| [ARCHITECTURE.md](ARCHITECTURE.md) | the C++ internals: items, the C/Main/Visualization split, the object factory, modules, solvers |
| [CODING_STYLE.md](CODING_STYLE.md) | naming, abbreviations, file headers, how to report an error from C++ (§10), what is deprecated |
| [WORKFLOW.md](WORKFLOW.md) | issue tracker, versioning, the four commit gates |
| [NEW_ITEM.md](NEW_ITEM.md) | how to set up a new item: the definition, what is generated, the C++, what to run |
| [GUI_MANUAL_CHECK.md](GUI_MANUAL_CHECK.md) | the manual check of the render window and the dialogs before a release, per platform |
| [../../definitions/README.md](../../definitions/README.md) | the item and structure definitions as Python, and the function declaration library |
| [../../tools/generators/README.md](../../tools/generators/README.md) | the new generator code and how to re-emit the definitions |
| [exudynRevisionInfo2026.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/revision/exudynRevisionInfo2026.md) | general information on the v1.11.0 → v2.0 restructuring: rules, facts, decisions |
| [exudynRevisionPlan2026b.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/revision/exudynRevisionPlan2026b.md) | **the plan that is open**: what the revision did not finish and what comes next, by group RG1 ... RG15 |
| [exudynRevisionPlan2026.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/revision/exudynRevisionPlan2026.md) | the finished plan of the 2026 revision, phases R0 ... R11 — a record; the revision completed as 1.12 |
| [exudynRevisionLog2026b.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/revision/exudynRevisionLog2026b.md) / [exudynRevisionLog2026.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/revision/exudynRevisionLog2026.md) | what each closed step actually turned out to be — the second is closed with its plan, the first is where the work of revision2026b is written up |
| [../../CONTRIBUTING.md](../../CONTRIBUTING.md) | how to contribute from outside |
| [CLAUDE.md](https://github.com/jgerstmayr/EXUDYN/blob/master/CLAUDE.md) | the working contract for Claude Code sessions |

```{toctree}
:hidden:
:maxdepth: 2

/docs/dev/GETTING_STARTED
/docs/dev/BUILD
/docs/dev/GIT
/docs/dev/ARCHITECTURE
/docs/dev/CODING_STYLE
/docs/dev/WORKFLOW
/docs/dev/NEW_ITEM
/docs/dev/GUI_MANUAL_CHECK
/docs/generated/deprecations
/definitions/README
/tools/generators/README
/tools/exudev/README
/CONTRIBUTING
```

## Repository layout

```
setup.py                                  the real build
exudynTemplate.sln                        VS2022 solution template (exudynPython.pyproj + cppsrc.vcxproj)
msvc/cppsrc.vcxproj                       the C++ source list; sources.json is generated from it
src/                                      hand-written C++: Graphics ImplMarkers ImplNodes ImplObjects
                                          Linalg Main Pymodules Solver System Tests Utilities
src/Autogenerated/                        generated C++ - never edit by hand
definitions/, tools/generators/          the generator input and the generators
python/exudyn/                            the shipped Python package
python/TestModels/                        the test models, nothing else
python/PerformanceModels/                 the performance models
python/MiniExamples/                      the generated mini examples
python/Examples/                          the examples
python/testing/                           the runners: runTestSuite.py and the rest
python/logs/                              testmodels/ examples/ performance/ tmp/
index.md                                  the table of contents of the documentation, hand-written: what comes in which order
docs/manual/                              the user manual, hand-written Markdown
docs/generated/                           the generated documentation (emitters, issue tracker)
docs/figures/                             the images of the documentation
docs/howTo/                               loose how-to notes, see below
tools/issueTracker/                       issue tracker and version source of truth
tools/exudev/                             the dev driver: build, test, docs, release
```

## Building and running

Three pages, in the order a new developer needs them:

| | |
|---|---|
| [GETTING_STARTED.md](GETTING_STARTED.md) | from nothing: clone, environment, `setupLocalWorkspace.py`, first build, first test run |
| [BUILD.md](BUILD.md) | the build itself, per platform, and what to do when it does not work |
| [GIT.md](GIT.md) | branches, commit messages, pull, push, merge, and what a contribution provides |

**Editors.** The everyday work happens in **VS Code** - the Python package, the definition
files, the documentation, and Claude Code. **Visual Studio 2022** is the debugger: stepping from
a Python script into a C++ item's `ComputeODE2LHS` with one debugger is the project's most
valuable development capability and is protected by design. `tools/setupLocalWorkspace.py`
prepares both.

**The driver**: one command, `exudev` - `exudev --help`, and `exudev -n <command>` to see what a
command would run without running it. Its commands are in
[`tools/exudev/README.md`](../../tools/exudev/README.md).

Entry points worth knowing:

- `src/Pymodules/PybindModule.cpp` — module creation.
- `src/Main/MainObjectFactory.h/.cpp` — item creation behind `mbs.AddNode(...)`; dispatch is
  on the `objectType` **string** from the Python dict, through a runtime class-factory registry.

## How-to notes

`docs/howTo/` was cut from 26 loose `.txt` files to 8 in the 2026-09 cleanup. Anything referring to
VS2017/VS2019, 32-bit builds, Python ≤ 3.7 or the pre-WSLg X-server era was deleted; the specifics
worth keeping were lifted into `buildQuirks.md`. The originals remain in git history, in the
archived internal repository and on GitHub.

Three of them are **pages of the documentation**, because a user or a first-time contributor
needs them:

| file | what it is for |
|---|---|
| [condaEnvironments.md](../howTo/condaEnvironments.md) | environment recipes, the package→feature map, the scipy pin |
| [sphinxDocs.md](../howTo/sphinxDocs.md) | building the documentation locally |

The other five are **maintainer notes**: they are in the repository, and they are linked here to
GitHub rather than to a page, because they are not published (#2585 — `exclude_patterns` in
`conf.py`).

| file | what it is for |
|---|---|
| [buildQuirks.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/howTo/buildQuirks.md) | traps that cost real time: MSVC↔GCC flags, `/bigobj`, ABI tags, debugging a startup crash |
| [gccVsMsvcTraps.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/howTo/gccVsMsvcTraps.md) | what MSVC accepts and GCC does not, and why |
| [visualStudio2022.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/howTo/visualStudio2022.md) | VS2022 install specifics and `dumpbin /version` |
| [convertVideosFfmpeg.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/howTo/convertVideosFfmpeg.md) | producing the demo animations |
| [matplotlibExamples.md](https://github.com/jgerstmayr/EXUDYN/blob/master/docs/howTo/matplotlibExamples.md) | plotting recipes used in examples |

macOS setup is covered in [docs/manual/gettingStarted.md](../manual/gettingStarted.md),
not here.

## Invariants

These are differentiators, not technical debt. Every restructuring step preserves them
(plan §7):

- Mixed Python/native debugging in VS2022 - the capability, not which editor is primary;
  the everyday work happens in VS Code.
- The setuptools-based fast build.
- No heavy C++ dependencies; vendored headers.
- The hard C++/Python split with dict-based validated interfaces.
- Runtime dependencies stay at numpy only. Development-only tools are unconstrained.