From b4d514e0a6d0989766f87c529d73ef85c9489d1f Mon Sep 17 00:00:00 2001 From: Alice Koniges <1103631+akoniges@users.noreply.github.com> Date: Thu, 23 Jul 2026 16:23:32 -1000 Subject: [PATCH] Add CLAUDE.md with build, test, and architecture guidance for Claude Code Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..db10e766 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,125 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What is GLVis + +GLVis is an OpenGL visualization tool and library for finite element meshes and functions, built on MFEM. It runs as a local GUI app, a socket server (default port 19916) receiving data from remote simulations, or in headless/batch mode. It also compiles to WebAssembly via Emscripten for browser use. + +## Build Systems + +GLVis must use the same build system as MFEM. + +### GNU Make + +MFEM must be built at `../mfem` (or set `MFEM_DIR`). + +```bash +make # Build glvis binary +make opt # Optimized build (GLVIS_DEBUG=NO) +make debug # Debug build (GLVIS_DEBUG=YES) +make -j4 # Parallel build +make style # Format source with astyle (required before PRs) +make status # Show current config +make install [PREFIX=] +make clean +make distclean +``` + +Key variables: `MFEM_DIR`, `GLVIS_DEBUG`, `GLVIS_USE_LIBPNG` (default YES), `GLVIS_USE_EGL` (default NO), `PREFIX`. + +### CMake + +In-source builds are prohibited. Requires CMake >= 3.10. + +```bash +mkdir build && cd build +cmake -G Ninja \ + -D CMAKE_BUILD_TYPE=Release \ + -D mfem_DIR=/path/to/mfem/build \ + -D GLVIS_USE_LIBPNG=ON \ + -D ENABLE_TESTS=TRUE \ + .. +cmake --build . --parallel 4 +cmake --install . +``` + +Key variables: `mfem_DIR`, `CMAKE_BUILD_TYPE`, `GLVIS_USE_EGL` (ON for headless Linux), `ENABLE_TESTS`, `GLVIS_BASELINE_SYS`. + +## Testing + +Tests are screenshot-based visual regression tests (SSIM comparison), only available via CMake. The `tests/data` directory is a git submodule from https://github.com/GLVis/data.git. + +```bash +# Install Python deps first +pip install -r tests/requirements.txt + +# Run all tests +xvfb-run -a ctest --verbose # Linux +ctest --verbose # macOS + +# Rebaseline (create new local baselines) +cmake --build . --target rebaseline + +# Run a single test manually +python3 tests/glvis_driver.py \ + -e ./glvis \ + -s tests/data/streams/.saved \ + -b tests/data/baselines/ \ + -a "-lw 1 -mslw 1 -nohidpi" +``` + +Pass threshold is SSIM >= 0.999. Test names: `ex1`, `ex2`, `ex3`, `ex5`, `ex6-dofs-numbering`, `ex9`, `ex22-scalar`, `ex22-vector`, `ex27`, `capacitor`, `distance`, `klein-bottle`, `laghos`, `mesh-explorer`, `mfem-logo`, `minimal-surface`, `mobius-strip`, `navier`, `quad`, `quadrature-1D`, `quadrature-lor`, `remhos`, `shaper`, `shifted`, `snake`. + +## Code Style + +```bash +make style # Runs astyle 3.1 with ../mfem/config/mfem.astylerc +``` + +This must pass before any PR is merged. Excludes `lib/gl2ps.c` and `lib/gl2ps.h` (external). + +## Architecture + +### Key Source Directories + +- **`glvis.cpp`** — main executable entry point; parses args, starts server or file reader +- **`lib/`** — core library built as `libglvis.a` + - **`gl/`** — OpenGL abstraction: `renderer_core` (modern GL core profile), `renderer_ff` (legacy fixed-function), shader management, GLSL sources in `gl/shaders/` + - **`sdl/`** — SDL2 windowing/event platform layer with platform-specific files (`sdl_mac.mm`, `sdl_x11.cpp`, `sdl_windows.cpp`) + - **`egl/`** — EGL headless rendering (Linux only) + - **`openglvis.cpp/hpp`** — `VisualizationScene` base class and camera + - **`vsdata.cpp/hpp`** — `VisualizationSceneScalarData`: base for all data visualization + - **`vssolution.cpp/hpp`** / **`vssolution3d.cpp/hpp`** — 2D/3D scalar field visualization + - **`vsvector.cpp/hpp`** / **`vsvector3d.cpp/hpp`** — 2D/3D vector field visualization + - **`aux_vis.cpp/hpp`** — main visualization thread initialization API + - **`stream_reader.cpp/hpp`** — socket server mode (receives `.saved` stream data) + - **`file_reader.cpp/hpp`** — file-based mesh/solution input + - **`script_controller.cpp/hpp`** — batch/scripting command processing + - **`palettes.cpp/hpp`** — color palette management + - **`font.cpp/hpp`** — FreeType font rendering + - **`gltf.cpp/hpp`** — glTF 3D export + - **`gl2ps.c/h`** — PDF/EPS/SVG export (external library, do not style-check) + - **`aux_js.cpp`** — Emscripten/WebAssembly bindings (web builds only) + +### Data Flow + +GLVis receives MFEM `Mesh` + `GridFunction` data either from a file or over a TCP socket (port 19916). The data is parsed in `stream_reader` or `file_reader`, stored in `data_state`, then dispatched to the appropriate `VisualizationScene` subclass (`vssolution`, `vssolution3d`, `vsvector`, `vsvector3d`) based on mesh dimension and field type. The scene renders via the GL renderer (`renderer_core` or `renderer_ff`), mediated by the SDL or EGL platform layer. + +## Dependencies + +**Required:** MFEM, OpenGL, GLEW >=2.1.0, GLM >=0.9.9.8, SDL2, FreeType 2, Fontconfig, `xxd` (build tool, not needed on Windows). + +**Optional:** libpng (default ON), libtiff (default OFF), EGL (headless Linux), GnuTLS (secure sockets via MFEM). + +Install on macOS: `brew install fontconfig freetype sdl2 glew glm libpng` + +Install on Ubuntu: `apt-get install libfontconfig1-dev libfreetype-dev libsdl2-dev libglew-dev libglm-dev libpng-dev` + +## Contribution Guidelines + +- C++17 required (as of v4.5) +- Feature branches use `-dev` suffix; PRs target `master` +- PR checklist: builds cleanly, passes `make style`, updates `CHANGELOG`, updates `INSTALL` if dependencies changed +- New external library code must be `#ifdef`-guarded and off by default +- New classes/methods need Doxygen-style comments