Skip to content

Compilation

Jump to bottom
AndreCox edited this page Dec 7, 2025 · 2 revisions

Compilation Guide

This page describes how to compile Fast-FEM on Linux and Windows, lists required dependencies, and provides step-by-step commands. The repository's CI (.github/workflows/build.yml) follows the same steps — these instructions are a human-friendly expansion.

Quick summary: the project uses CMake and FetchContent to fetch ImGui, ImGui-SFML, SFML and Eigen. You still need basic system development packages (X11, OpenGL, audio, fonts, etc.) and a working C++ toolchain.

Supported platforms: Linux (Ubuntu/Debian), Windows (Visual Studio + vcpkg or MSYS2).

Prerequisites (tools):

  • CMake: modern CMake (>= 3.16 recommended). See: https://cmake.org
  • A C++17 compiler: GCC/Clang on Linux, MSVC (Visual Studio 2019/2022) or MinGW/MSYS2 on Windows.
  • Git: to clone the repository and allow CMake FetchContent to fetch subprojects.

Primary upstream libraries used by the project (links):

Linux (Ubuntu / Debian) — recommended steps

  1. Install system dependencies (example for Ubuntu/Debian):
sudo apt-get update
sudo apt-get install -y build-essential cmake git \
    libx11-dev libxrandr-dev libxcursor-dev libxi-dev libxext-dev \
    libgl1-mesa-dev libudev-dev libopenal-dev libasound2-dev pkg-config \
    libogg-dev libvorbis-dev libflac-dev libfreetype6-dev

Notes:

  • These packages provide headers and libraries required when building SFML and the GUI (X11, OpenGL, audio backends, fonts and codecs).
  • The project uses CMake FetchContent to pull SFML, ImGui, ImGui-SFML, and Eigen automatically. The system packages above satisfy build-time native dependencies.
  1. Configure and build (out-of-source build):
# from repository root
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -- -j$(nproc)
  1. Running the binary and resources:
  • After build, the produced executable is build/main (or build/<config>/main depending on platform). The CMakeLists copies resources to the executable folder during POST_BUILD; check build/resources or build/<config>/resources.
  • For details on running the application, see Running.
  1. Debug build:
cmake -S . -B build/debug -DCMAKE_BUILD_TYPE=Debug
cmake --build build/debug --config Debug -- -j$(nproc)
  1. Packaging (example):
mkdir -p dist && cp build/main dist/ && cp -r build/resources dist/
tar -czf fastfem-linux.tar.gz -C dist .

Windows (recommended: Visual Studio + vcpkg)

Option A — Visual Studio + vcpkg (recommended for reproducible builds):

  1. Install Visual Studio 2019/2022 with "Desktop development with C++" workload.

  2. Install and bootstrap vcpkg:

# run in PowerShell or cmd
git clone https://github.com/microsoft/vcpkg.git C:\\vcpkg
C:\\vcpkg\\bootstrap-vcpkg.bat
# install commonly required runtime libs
C:\\vcpkg\\vcpkg.exe install sfml:x64-windows libogg:x64-windows libvorbis:x64-windows libflac:x64-windows freetype:x64-windows
  1. Configure CMake to use vcpkg toolchain and build:
cmake -S . -B build -A x64 -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release

Notes:

  • If you installed additional packages via vcpkg (e.g., SFML, freetype), CMake should find these automatically when using the vcpkg toolchain file.
  • The GitHub Actions workflow included in this repo also uses vcpkg for Windows in a similar way.
  • For instructions on running the built executable, refer to Running.

Option B — MSYS2 (MinGW) (alternative):

  1. Install MSYS2: https://www.msys2.org and use the mingw64 environment.
  2. Install toolchain and SFML within MSYS2:
# in MSYS2 MinGW64 shell
pacman -Syu
pacman -S --needed mingw-w64-x86_64-toolchain mingw-w64-x86_64-sfml mingw-w64-x86_64-cmake git
  1. Configure and build using the MinGW generator:
cmake -S . -B build -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -- -j8
  • See Running for details on executing the application after build.

CI / Reproducible build notes

  • The repository contains .github/workflows/build.yml which demonstrates how to configure and build on Linux and Windows with actions. It installs system packages on Ubuntu, uses vcpkg on Windows, runs CMake configure and build steps, and packages artifacts.
  • If you want a local environment that mirrors GitHub Actions, follow the Linux/Apt or Windows/vcpkg steps above.

Troubleshooting

  • Missing headers like X11/Xlib.h or GL/gl.h — install the X11/OpenGL development packages listed in the Linux prerequisites.
  • Linker errors for audio or codecs — ensure libopenal-dev, libogg-dev, libvorbis-dev, and libflac-dev are installed on Linux, or install corresponding vcpkg packages on Windows.
  • CMake cannot find SFML or ImGui — confirm network access for FetchContent or install SFML via your package manager/vcpkg and point CMake to the toolchain file.
  • If using vcpkg on Windows, remember to use the -A x64 generator (or matching triplet) and the -DCMAKE_TOOLCHAIN_FILE argument.

Quick reference commands

  • Configure Release (Linux):
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -- -j8
  • Configure Debug (Linux):
cmake -S . -B build/debug -DCMAKE_BUILD_TYPE=Debug
cmake --build build/debug --config Debug -- -j8
  • Windows + vcpkg example:
# bootstrap vcpkg once
git clone https://github.com/microsoft/vcpkg.git C:\\vcpkg
C:\\vcpkg\\bootstrap-vcpkg.bat
# install packages
C:\\vcpkg\\vcpkg.exe install sfml:x64-windows libogg:x64-windows libvorbis:x64-windows libflac:x64-windows freetype:x64-windows
# configure + build
cmake -S . -B build -A x64 -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
  • For instructions on running the application after compilation, see Running.

Clone this wiki locally