Skip to content

Running

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

Running Fast-FEM

This page explains how to run the built Fast-FEM binary on Linux and Windows, how to run a debug build under a debugger, how to run packaged artifacts, and common runtime troubleshooting steps.

Important: The project CMakeLists contains a POST_BUILD step that copies the resources directory to the executable output directory. If you run the binary from a different location, ensure the resources folder is next to the executable or point the program to the correct resources path.

Where the binaries are

  • Linux: typical output paths are build/main or build/debug/main depending on the build directory used.
  • Windows (Visual Studio + vcpkg): typical output paths are build\Release\main.exe or build\Debug\main.exe (or build\main.exe when using single-folder builds).

Run examples — Linux

  • Run the Release binary (from repository root):
./build/main
  • Run the Debug binary:
./build/debug/main
  • If the binary cannot find resources, copy them to the build dir and run:
cp -r resources build/
./build/main
  • The project uses CMake FetchContent to fetch SFML, ImGui and Eigen. In many cases those libraries are either built into the executable (static) or their runtime artifacts are copied into the build output, so setting LD_LIBRARY_PATH is usually not necessary.

Only set LD_LIBRARY_PATH if your particular build produced shared libraries that are not on the system library search path (for example during a subbuild where shared .so files are placed in build/ or build/_deps). Example (conditional):

# prepend the build folder containing .so files to the library path for this run
LD_LIBRARY_PATH=build:$LD_LIBRARY_PATH ./build/main
# or point to a specific deps folder
LD_LIBRARY_PATH=build/_deps/some_lib/lib:$LD_LIBRARY_PATH ./build/main
  • Run under gdb (example):
gdb --args ./build/main [optional-args]
# then in gdb: run

Run examples — Windows (PowerShell / CMD)

  • Run the Release binary (PowerShell):
.\build\Release\main.exe
  • Run the Debug binary (PowerShell):
.\build\Debug\main.exe
  • If you used vcpkg and the app fails with missing DLLs (e.g. sfml-graphics-2.dll), copy the runtime DLLs into the executable directory. Example PowerShell copy (adjust C:\vcpkg\installed\x64-windows\bin if your vcpkg is elsewhere):
Copy-Item -Path "C:\vcpkg\installed\x64-windows\bin\*" -Destination ".\build\Release" -Recurse -Force
.\build\Release\main.exe

  • Alternatively, use vcpkg integrate install and run from a developer command prompt where the runtime DLLs are available on PATH.

  • Run from Visual Studio: open the build folder or the generated solution, set main as the startup project and press F5.

Running packaged artifacts

  • If you used the included packaging step from the repo's CI to produce fastfem-linux.tar.gz:
tar -xzf fastfem-linux.tar.gz -C dist
cd dist
./main
  • For a Windows zip created from CI, unzip and run main.exe from the extracted folder; ensure DLLs are present in the same folder.

Debugging tips

  • If the program crashes on startup, run it under a debugger to get the stack trace (gdb on Linux, Visual Studio or WinDbg on Windows).
  • Use strace ./build/main (Linux) to see failing syscalls (useful for missing files or permission issues).
  • Standard runtime errors and fixes:
    • Missing DLL / shared library: copy the required runtime libraries next to the executable or update PATH / LD_LIBRARY_PATH.
    • Missing resources (images / fonts): ensure the resources folder is adjacent to the executable or supply the path via command-line arguments if the program supports it.

Quick checklist before running

  • Built executable present: check build/ or build/Release.
  • Resources copied: verify build/resources or copy manually: cp -r resources build/ (Linux) or Copy-Item on Windows.
  • Runtime libraries available: ensure system packages or vcpkg-provided DLLs are accessible.

Clone this wiki locally