eepp/.agent/rules/build-project.md

Build Instructions

The build configurations in .ecode/project_build.json are the source of truth for the developer's local build workflows. Check that file before selecting a generator, backend, or build flags. In particular, do not use an AddressSanitizer build to evaluate runtime performance.

Release Performance Builds (Linux)

For performance investigations, use the eepp-linux-ninja configuration from .ecode/project_build.json. At the time of writing, its commands are:

premake5 --disable-static-build --with-debug-symbols --with-backend=SDL3 ninja

ninja -C make/linux release

This produces an optimized release build with debug symbols and without AddressSanitizer. Run the release executable (for example, bin/eepp-ui-html) when measuring performance. Recheck .ecode/project_build.json before use because the local configuration may change.

Debug and Unit-Test Builds

All build commands must be executed from the root project directory. Follow these steps to build the project:

Step 1: Regenerate Project Files

Always regenerate the project files before compiling or running tests after making changes. Do this even for edits to existing files, because the checked-in makefiles can be stale and may reference removed files or miss recently added targets.

• Tool: Use premake4 if installed; otherwise, fallback to premake5 (the parameters are identical).
• Linker Flag (--with-mold-linker): This flag is conditional. If the mold linker is installed on the system, you must include it to speed up linking. If mold is not installed, omit the flag.

Command (if mold is installed): premake4 --disable-static-build --with-mold-linker --with-debug-symbols --address-sanitizer gmake

Command (if mold is NOT installed): premake4 --disable-static-build --with-debug-symbols --address-sanitizer gmake

Step 1a: Format Changed Files

After editing any C or C++ source file (.c, .cpp, .h, .hpp), you must run clang-format on all modified files to ensure consistent formatting with the project's style (defined in .clang-format at the repository root).

Command (formats all currently modified tracked files at once): git diff --name-only -- '*.c' '*.cpp' '*.h' '*.hpp' | xargs clang-format -i

Run this after all edits and before attempting to compile.

---

Step 2: Compile the Project

To compile the project in debug mode, execute the make command, ensuring you point to the correct directory for your current Operating System.

Always use all processors reported by the platform when selecting the parallel job count. On Linux and other systems with nproc, use -j$(nproc) exactly; do not substitute an arbitrary fixed value such as -j4. Use the platform-equivalent processor-count command where nproc is unavailable.

The valid OS directory names are: windows, macosx, linux, bsd, haiku.

Run the following command, replacing <os_name> with the correct environment: make -C make/<os_name> -j$(nproc)

Examples:

• Linux: make -C make/linux -j$(nproc)
• macOS: make -C make/macosx -j$(sysctl -n hw.ncpu)
• Windows: make -C make/windows -j%NUMBER_OF_PROCESSORS%

Running GUI Examples Under Xvfb

Xvfb does not support the multisampled OpenGL contexts requested by some eepp examples. In particular, src/examples/ui_html/ui_html.cpp normally requests 4x MSAA. Launching that binary through xvfb-run or projects/scripts/xvfb-run-eepp can therefore fail immediately with Could not create window, exiting, even though the application works on a real display.

• Do not treat this window-creation failure as evidence of a bug in the feature being tested.
• Unit tests normally request a non-multisampled context and are unaffected.
• For a temporary headless diagnostic of an example, make the diagnostic-only execution path request 0 MSAA, run it through projects/scripts/xvfb-run-eepp, and revert the temporary example instrumentation afterward.
• Never weaken the example's normal graphics configuration merely to accommodate Xvfb.