thwyigo/cmake-sfml-bloat-project

A not-so-minimal CMake SFML project template

This template is a little more bloated than cmake-sfml-project. It should help you to write tests, manage runtime assets (such as sprites and audio), create a Windows installer, a Nix derivation and an AppImage.

I test this template on Linux and Windows, though it might work on MacOS.

Structure of the project

Directory	Description
src/	C++ source files
src/include/	C++ header files
data/	Runtime assets
tools/	Tools that help with project building and packaging
test/	C++ tests with CTest

Understanding what each file does

CMakeLists.txt

This is the most important file. It is the first file read by CMake, which is a cross platform build automation tool, which can generate files for various build systems, e.g. Visual Studio solution, Makefile, Ninja.

Building a CMake project requires 2 steps: configuring and building.

• Configuring is just the generation of build system files. The typical way to do it is

  cmake -S . -B out -DCMAKE_BUILD_TYPE=Release # or Debug
      

  It will pick a build system automatically depending on what you have installed on your system and generate it’s files in out/ directory.

• Building will compile the source code.

  cmake --build out # out is the name of the directory where the project was configured
      

If it doesn’t work, it might be because you are using a multi-configuration generator, if this is the case, you should do the following instead:

cmake -S . -B out
cmake --build out --config Release

Building the project in any of the above ways will fetch SFML and Boost source code and compile it. It will also set the data/ directory location to an absolute path, so the generated executable won’t be portable. If you’re interested in sharing a pre-built binary, you’ll probably need to pass some options to cmake on the command line or use CMakePresets.json.

CMake options for this project

Option	Description	Default
fetchSFML	Download and compile SFML automatically	ON
fetchBoost	Download and compile Boost automatically	ON
USE_RELATIVE_PATHS	Set some variables as relative paths to install directory	OFF
BUILD_SHARED_LIBS	Build shared libraries	ON
CONFIG_PACKAGING	Generate packaging files	OFF

If you set on USE_RELATIVE_PATHS, keep in mind that files in the data folder are copied to the output directory only when installing the project, i.e. if you build, but don’t install the project, DATA_PATH will be an invalid path.

Additional notes on project building

External libraries will be fetched by default. Note that if you’re on Linux, SFML require it’s dependencies to be installed.

Another option is to turn fetchX option OFF and install that dependency through your package manager. Make sure you install the correct version of it. You can check which version is needed by searching for it in CMakeLists.txt.

CMakePresets.json

This file contains CMake presets that define options, variables, output and install directories. You can use them like this:

cmake --preset x64-debug-linux
cmake --build --preset x64-debug-linux
ctest --preset x64-debug-linux

Some IDEs list these presets as Configure / Build “configurations” in their GUI.

default.nix

This is the file that is read automatically by nix-build on Linux. Nix is a package manager that can build packages from source.

shell.nix

This is the file that is read automatically by nix-shell on Linux. Nix shell provides a development environment with all the dependencies installed. Try opening your text editor or IDE inside nix-shell and see how easy it is!

Including files

Files located in src/include/ are already in the include search path, so you can just #include "file.hpp".

Using assets from the data/ folder

Please, don’t try to reference content in data/ like this:

variable.loadTexture("../data/Texture.png");

This is not portable. Use DATA_PATH defined in config.hpp instead

#include "config.hpp"
/* The file config.hpp is generated by CMake through config.hpp.in. Your LSP
 * won't work if the project was never configured before */

variable.loadTexture((DATA_PATH / "Texture.png").generic_string());

The above method is generic and works for any situation, but if you’re trying to reference a file that would be used with SFML’s loadFromFile() function, you should give AssetManager.hpp a try. It defaults to the data/ directory and saves memory by not duplicating assets in memory.

#include "AssetManager.hpp"
#include <SFML/Graphics.hpp>

// Important to take the return value by &reference if you want to save memory
sf::Texture& texture = AssetManager<sf::Texture>::Get("Texture.png");
Sprite.setTexture(texture);

Using debug.hpp

debug.hpp provides macros that only work in Debug mode. In Release mode, these macros are ignored, in fact, they’re replaced with empty lines.

#include "debug.hpp"
/* Any variable that can be printed with `std::cerr << var` can be used with
 * these debug macros */

int myInt = 4;
// Print the line number with a message, variable name and value.
db_line("Useful message", myInt);
// Print the file name with line number, a message, variable name and value.
db_file("Useful message", myInt);
// You can give multiple variables to the macro.
db_line("Useful message", myInt, var1, var2, var3);

Generating an installer / package

Packaging files can be generated at the configure step by setting CONFIG_PACKAGING option to ON. For example:

cmake -S . -B out -DfetchSFML=OFF -DfetchBoost=OFF -DCONFIG_PACKAGING=ON

Generated files are based on .in files, e.g. nix/derivation.nix is generated by nix/derivation.nix.in.

Windows MSI

1. Install Visual Studio Build Tools

   winget install Microsoft.VisualStudio.2022.BuildTools
       

2. Install WIX toolset
   1. You can install WIX with Scoop. First open PowerShell and install Scoop.

      Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
      irm get.scoop.sh | iex
              

   2. Run scoop install wixtoolset
3. Open x64 Native Tools Command Prompt for VS 2022
4. Generate the installer

   cd "C:\path\to\project\root"
   cmake --preset x64-release-windows -DUSE_RELATIVE_PATHS=ON && cmake --build --preset x64-release-windows && cpack --preset x64-WIX
       

5. The directory where the .msi was generated will be informed in the command output

Linux AppImage

1. Install docker
2. Check CMake flags in ./tools/appimage/Dockerfile.in
3. Generate packaging files
4. docker build -t myproject-appimage tools/appimage/
5. docker run --rm -v $PWD:/source -w /source myproject-appimage

You can open an interactive shell inside the docker container with docker run -ti --rm -v $PWD:/source -w /source myproject-appimage bash

IDE / text editor integration

Some IDEs / text editors have CMake support. The easiest ones to use are Visual Studio and VSCodium with CMake Tools, clangd and Native Debug extensions.

You might need to check Cmake: Allow Unsupported Presets Versions option and set Cmake: Copy Compile Commands to compile_commands.json if you’re using CMake Tools and clangd.

License

All files in this repository are licensed under WTFPL (see LICENSE file).

This work is free software. It comes without any warranty, to the extent permitted by applicable law. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See http://www.wtfpl.net/ for more details.