Home / Installation
Installation
Requirements, external dependencies, building with make and verifying the installation.
Requirements
The project targets a Linux environment (developed and tested under WSL2). You need the following tools and libraries:
| Tool / library | Purpose |
|---|---|
clang++ | C++ compiler. The Makefile invokes it explicitly, using the C++17 standard. |
make | Build system (compilation and linking orchestration). |
| SFML | Window, graphics context, input and networking — used by the interface plugin. Linked modules: graphics, window, system, network. |
X11 (libX11) | Windowing system on Linux (linked via -lX11), required by the interface plugin. |
SFML and X11 are only needed for the graphical interface plugin
(user_interface.so). The engine core and the renderers depend only on the C++ standard library.
Bundled dependencies
Two header-only libraries are included in the repository under srcs/external/ — nothing to install. The Makefile makes them available at build time via -isystem srcs/external:
- nlohmann/json (
srcs/external/nlohmann/json.hpp) — reading and writing scene files in JSON format. - stb_image (
srcs/external/stb_image.h) — loading images (textures) and exporting renders to PNG.
Install SFML and X11 (Debian / Ubuntu)
On a Debian- or Ubuntu-based distribution:
sudo apt update
sudo apt install clang make libsfml-dev libx11-devThe packages are named libsfml-dev (SFML, all modules) and libx11-dev
(X11) on Debian/Ubuntu. Adapt the package names to your distribution.
Building
From the repository root:
makeEach translation unit is built with the flags
-Wall -Wextra -Werror -std=c++17 -fPIC -g -fsanitize=address. Warnings are therefore
treated as errors (-Werror) and AddressSanitizer
(-fsanitize=address) is enabled to catch memory errors at runtime.
The build produces the following artifacts:
| Artifact | Description |
|---|---|
./raytracer | Main executable (engine core). |
plugins/user_interface.so | Graphical interface plugin (linked against SFML and X11). |
plugins/renderer_default.so | "Default" renderer (full render to image). |
plugins/renderer_viewport.so | "Viewport" renderer (interactive progressive render). |
The Makefile creates the ./plugins directory if needed and places the three shared
libraries there. The executable is produced at the repository root.
Plugins are loaded at runtime from the ./plugins directory
(relative path). Run ./raytracer from the project root, where that
directory lives, otherwise plugin loading fails.
Makefile targets
| Command | Effect |
|---|---|
make / make all | Builds the executable and the three plugins. |
make clean | Removes intermediate .o object files. |
make fclean | Runs clean, then removes the executable and the .so plugins. |
make re | Equivalent to fclean then all (full rebuild). |
Verify the installation
Once the build is complete, a few quick commands confirm that everything works:
# Version (prints "raytracer version 1.0.0")
./raytracer --version
# Help (lists the command-line options)
./raytracer --help
# First render to a PNG, without the graphical interface
./raytracer -r output.png tests/configs/subject.jsonThe last command uses headless mode (-r / --render): it
renders the scene directly to an output.png file, without opening a window. If the
output name is omitted, the default file is render.png. See the
Usage page for the full list of options and the scene format.
WSL note
Under WSL, the graphical interface forces software
OpenGL rendering (Mesa / llvmpipe) to stay stable when several windows are open at the
same time. A Setting vertical sync not supported message may appear at startup: it is
harmless and does not prevent the program from running.
Troubleshooting
If something goes wrong (missing dependencies, plugins not found, windows failing to open under WSL, AddressSanitizer warnings…), start with a clean rebuild:
make reFor common issues and their solutions, refer to the FAQ.