cmake-sfml-project is the starting point SFML developers keep forking

A template, not a library, and that changes what you adopt

The CMake SFML Project Template is described as a repository template that should allow a fast and hassle-free kick start of your next SFML project using CMake. The framing matters, because you are not adding a dependency here, you are forking a starting point.

GitHub's template feature lets you create a repository from this one without inheriting its Git history, so your game starts with a clean commit log rather than with the template's commits. The README also points out that you can use the project without a GitHub account at all, by downloading the contents as a ZIP archive and unpacking it locally, which avoids Git entirely if you prefer.

What you get is deliberately minimal, and the documentation says so. There is a basic CMake script to build your project and link SFML on any operating system, and a basic GitHub Actions script for all major platforms. The template starts out very basic, but might receive additional features over time.

That last sentence is the honest framing of the whole project. It is a starting point that the SFML maintainers keep current, not a framework with an API.

The repository itself is five things: a README.md, a LICENSE.md, a CMakeLists.txt, a .github directory and a src/ directory. The primary language recorded for the repository is CMake, the default branch is master, and the last push was on 2026-08-11.

FetchContent builds SFML alongside your code

The most consequential line in the template is the one about upgrading SFML, because it explains the whole build model.

SFML is found via CMake's FetchContent module. FetchContent automatically downloads SFML from GitHub and builds it alongside your own code. The documentation gives two reasons for that beyond the convenience of not having to install SFML yourself: it ensures ABI compatibility, and it simplifies things like specifying static versus shared libraries.

ABI compatibility is the argument that decides it for most people. If SFML is a system package on one machine and a locally built copy on another, the compiler flags, the standard library and the SFML build options can differ, and you get link errors or crashes that look like your own code. Building one copy from source, once, removes that whole class of problem.

The cost is build time and disk space, since SFML is compiled as part of your project every time you configure, unless the build cache does its job. And the version is fixed in one place: modifying what version of SFML you want is as easy as changing the GIT_TAG argument, and the template currently uses SFML 3 via the 3.1.0 tag.

So the version decision is one line in CMakeLists.txt, and the consequence of that line is that your project pins an exact SFML release by tag.

Turning the template into your project

The quick start is a numbered list, and the middle steps are the ones that matter.

You install Git and CMake, using the system package manager if you have one, and then create your repository from the template. Clone it, open it in your editor, and then the real work starts in CMakeLists.txt: rename the project and the target name of the executable to whatever you want, making sure you change all occurrences.

Then the source list. If you want to add or remove any .cpp files, you change the source files listed in the add_executable call in CMakeLists.txt to match what your project requires, and if you plan to keep the default main.cpp file then no changes are required there.

Then the libraries. If your code uses the Audio or Network modules, you add SFML::Audio or SFML::Network to the target_link_libraries call, alongside the existing SFML::Graphics library that is being linked.

That last step is the one that catches people. The template links Graphics by default, and Audio and Network are opt-in, which makes sense for a minimal starting point but means the first thing to do when your game has sound is to edit the link list.

On Linux, the SFML dependencies have to be installed from the system package manager, and the README gives the Debian and Ubuntu command:

   sudo apt update
   sudo apt install \
       libxrandr-dev \
       libxcursor-dev \
       libxi-dev \
       libudev-dev \
       libfreetype-dev \
       libflac-dev \
       libvorbis-dev \
       libgl1-mesa-dev \
       libegl1-mesa-dev \
       libharfbuzz-dev \
       libmbedtls-dev \
       libssh2-1-dev

That list is long, and it is the reason a lot of first builds on Linux fail: the graphics and audio dependencies are needed even if you only plan to draw shapes.

Building from the command line or from an IDE

Step 8 of the quick start covers the build itself, and the template is agnostic about how you drive it.

Most popular IDEs support CMake projects with very little effort on your part, and the documentation links four of them: VS Code through the CMake extension, Visual Studio with its CMake projects support, CLion with its CMake support, and Qt Creator. For Windows there is a separate section that recommends a Visual Studio workspace as the simplest route, with Visual Studio configuring the CMake project automatically so you can build and run as normal.

Using CMake from the command line is straightforward as well, and the documentation asks you to run the commands in the root directory of the project you just created:

   cmake -B build
   cmake --build build

The out-of-source build into a build/ directory is the modern convention and it keeps the source tree clean, which matters more than it sounds when a template is copied around and modified.

If you prefer Visual Studio on Windows and have already cloned the repository, the README says you can open the folder directly, and if you have not cloned it, you can clone it from within Visual Studio. Either way you end up with the same CMake configuration.

The options you are most likely to change

The But I want to... section of the README is a list of the adjustments most projects end up making, and it is the part of a template that carries the most practical value.

CMake options can be modified by adding them as configuration parameters with a -D flag, or by modifying the contents of CMakeCache.txt and rebuilding. The compiler is changed through the CMAKE_<LANG>_COMPILER options, and in particular you modify CMAKE_CXX_COMPILER to point at the compiler you want.

Optimisation is handled through CMAKE_BUILD_TYPE, which CMake uses to abstract away specific optimizer flags. The project recommends Release builds by default, which enable optimizations, with Debug builds enabling debug symbols but disabling optimizations. If you are on a multi-configuration generator, which is often the case on Windows, you modify the CMAKE_CONFIGURATION_TYPES option instead.

Generators are the last one and the one with a catch. While CMake will attempt to pick a suitable default generator, some systems offer several, and Ubuntu for example offers Makefiles and Ninja. To change it you reconfigure with a -G flag, and here the documentation is explicit that you cannot simply modify an entry in the CMakeCache.txt file as you could for the options above. You then rebuild with the new generator.

The CMAKE_BUILD_TYPE and CMAKE_CXX_COMPILER knobs are cache variables, so they persist. The generator is not, which is why the generator change needs a reconfigure rather than an edit.

What a template cannot tell you

There is a limit to what a five file template can tell you, and it is worth being straight about it.

The documentation is a getting-started guide, and there is no reference section beyond the But I want to... list. It does not describe the windowing options, the input handling, the sprite and audio APIs, or the module structure SFML itself provides, because that is SFML's documentation to hold, not the template's.

The CI coverage is described as a basic GitHub Actions script for all major platforms. The template's .github directory is the entire automation story, and the README does not set out which platforms are covered, what the workflow actually runs, or how the built artefacts are delivered. A team that needs signed builds, matrix testing across compiler versions, or deployment to a platform store will be writing that workflow themselves, and the template's contribution is that it starts from something that already configures and builds.

The other limitation is the nature of a template itself. The moment you fork it, the two copies diverge, and the template's own improvements, which the README promises might arrive over time, will not reach your fork. Projects that want ongoing upstream fixes are better served by vendoring the small amount of configuration themselves, and the value here is that you can start with a working build in minutes and then keep the CMake logic under your own control.

The custom licence in LICENSE.md is the last thing to check before you publish anything built from it.

Editorial conclusion

cmake-sfml-project suits someone starting a new SFML game who wants a working CMake build and a CI workflow in the first minute rather than a day of build setup, and it is the wrong tool for an existing project, since it is a starting point rather than something to integrate. Before using it, decide whether you want SFML fetched and built from source, because that is what the template does, and change the GIT_TAG argument if you need a different version than the 3.1.0 tag it currently uses.

Frequently asked questions

Official sources

1. Issues
2. README
3. SFML/cmake-sfml-project on GitHub