GR-raytracing/build.md

Build guide

Run these commands from the repository root. The build uses GNU Make and produces standalone executables under build/Release/ or build/Debug/.

Dependencies

The default CPU build needs:

• A C11 compiler and OpenMP runtime (for example, GCC with libgomp).
• GNU Make.
• libpng headers and library for PNG output.

Optional dependencies are CFITSIO and pkg-config for HDR/FITS output, and HIP/ROCm with hipcc and a compatible GPU for HIP PSF accumulation.

CPU build

make -j

With no explicit SPACETIME setting, this builds both supported spacetimes:

Executable	Spacetime
build/Release/minkowski_sky	Flat Minkowski spacetime
build/Release/schwarzschild_sky	Analytic Schwarzschild in ingoing Kerr–Schild coordinates

To build only one:

make -j SPACETIME=minkowski backend
make -j SPACETIME=schwarzschild backend

Each executable contains one metric provider, selected at compile time. PSF_BACKEND=cpu is the default. Release builds use -O2 -DNDEBUG; the default compiler flags also include -march=native, targeting the build machine's CPU. For a binary intended for other CPUs, override CFLAGS:

make -B -j CFLAGS='-std=c11 -pipe -Wall -Wextra -Wpedantic'

For a Debug build (-O0 -g3):

make -j BUILD_TYPE=Debug

Debug executables are placed in build/Debug/.

Output formats

PNG is enabled by default. If libpng is unavailable, build with binary PPM output instead and use a .ppm output filename:

make -B -j ENABLE_PNG=0

To enable the optional --hdr-output switch, install CFITSIO and pkg-config, then build the desired spacetime with ENABLE_HDR=1:

make -j SPACETIME=schwarzschild ENABLE_HDR=1 backend

The executable keeps its usual name, build/Release/schwarzschild_sky. --hdr-output writes a linear RGB FITS file alongside the ordinary single-frame image; see usage.md. Use ENABLE_HDR=0 to rebuild without this feature.

Optional HIP PSF acceleration

make -j PSF_BACKEND=hip SPACETIME=minkowski backend
make -j PSF_BACKEND=hip SPACETIME=schwarzschild backend

These produce build/Release/minkowski_sky_hip and build/Release/schwarzschild_sky_hip, separately from the CPU executables. HIPCC can override the default hipcc command. ENABLE_HDR=1 can be combined with either HIP build.

HIP accelerates cache-eligible PSF accumulation; ray tracing and catalog mapping remain on the CPU. PSFs requiring direct evaluation retain the CPU reference path with ordered HDR transfers. HIP initialization or execution errors terminate the render instead of silently selecting the CPU backend.

Rebuilding and checks

Build type, spacetime, HDR, and PSF backend configurations have separate object paths. Changes to flags such as ENABLE_PNG, CC, or CFLAGS require a forced rebuild with make -B and the intended settings. make clean removes the entire build/ directory; keep rendered images and other retained output under output/.

Inspect the available runtime options:

./build/Release/minkowski_sky --help
./build/Release/schwarzschild_sky --help

Run CPU regression checks:

make test

The CPU suite includes both coordinate-camera builders, CLI validation, small PNG renders, and single-frame/movie lens-map agreement. The reference image checks require Python 3 and CFITSIO. The original Schwarzschild HDR fixture is retained with a float32 relative tolerance of 2^-23 (zero absolute tolerance): replacing the specialized static tetrad with metric-based orthonormalization changes four components by one ULP. The Minkowski fixture still requires exact equality.

The HIP regression requires an actual compatible GPU. The Make target builds the test executable; run it separately:

make PSF_BACKEND=hip SPACETIME=minkowski hip-psf-test
./build/Release/test_hip_psf

For rendering with real stellar data, continue with README.md and the rendering guide.