Use FetchContent to depend on SFML

Author: ChrisThrasher

.github/workflows/ci.yml

@@ -17,37 +17,25 @@ jobs:
         - { name: Linux Clang,    os: ubuntu-latest, flags: -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ }
         - { name: MacOS XCode,    os: macos-latest  }
         config:
-        - { name: Shared, flags: -DSFML_STATIC_LIBRARIES=OFF -DBUILD_SHARED_LIBS=TRUE }
-        - { name: Static, flags: -DSFML_STATIC_LIBRARIES=ON -DBUILD_SHARED_LIBS=FALSE }
+        - { name: Shared, flags: -DBUILD_SHARED_LIBS=TRUE }
+        - { name: Static, flags: -DBUILD_SHARED_LIBS=FALSE }
 
     steps:
     - name: Install Linux Dependencies
       if: runner.os == 'Linux'
       run: sudo apt-get update && sudo apt-get install libxrandr-dev libxcursor-dev libudev-dev libopenal-dev libflac-dev libvorbis-dev libgl1-mesa-dev libegl1-mesa-dev
 
-    - name: CMake SFML Project - Checkout Code
+    - name: Checkout
       uses: actions/checkout@v3
 
-    - name: SFML - Checkout Code
-      uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-        repository: SFML/SFML
-        ref: 2.6.x
-        path: SFML
-
-    - name: SFML - Configure CMake
-      shell: bash
-      run: cmake -S $GITHUB_WORKSPACE/SFML -B $GITHUB_WORKSPACE/SFML/build -DCMAKE_INSTALL_PREFIX=$GITHUB_WORKSPACE/SFML/install -DCMAKE_VERBOSE_MAKEFILE=ON ${{matrix.platform.flags}} ${{matrix.config.flags}}
-
-    - name: SFML - Build
+    - name: Configure
       shell: bash
-      run: cmake --build $GITHUB_WORKSPACE/SFML/build --config Release --target install
+      run: cmake -S . -B build -DCMAKE_INSTALL_PREFIX=install ${{matrix.platform.flags}} ${{matrix.config.flags}}
 
-    - name: CMake SFML Project - Configure CMake
+    - name: Build
       shell: bash
-      run: cmake -S $GITHUB_WORKSPACE -B $GITHUB_WORKSPACE/build -DCMAKE_INSTALL_PREFIX=$GITHUB_WORKSPACE/install -DCMAKE_VERBOSE_MAKEFILE=ON -DSFML_DIR=$GITHUB_WORKSPACE/SFML/install/lib/cmake/SFML ${{matrix.platform.flags}} ${{matrix.config.flags}}
+      run: cmake --build build --config Release
 
-    - name: CMake SFML Project - Build
+    - name: Install
       shell: bash
-      run: cmake --build $GITHUB_WORKSPACE/build --config Release --target install
+      run: cmake --install build --config Release

CMakeLists.txt

@@ -1,7 +1,11 @@
 cmake_minimum_required(VERSION 3.15)
 project(CMakeSFMLProject LANGUAGES CXX)
 
-find_package(SFML 2.5.1 COMPONENTS graphics REQUIRED)
+include(FetchContent)
+FetchContent_Declare(SFML
+    GIT_REPOSITORY https://github.com/SFML/SFML.git
+    GIT_TAG 2.6.x)
+FetchContent_MakeAvailable(SFML)
 
 add_executable(CMakeSFMLProject src/main.cpp)
 target_link_libraries(CMakeSFMLProject PRIVATE sfml-graphics)

README.md

@@ -1,38 +1,80 @@
 # CMake SFML Project Template
 
-This repository template, should allow for a fast and hassle-free kick start of your next SFML project using CMake.  
+This repository template should allow for a fast and hassle-free kick start of your next SFML project using CMake.
 Thanks to [GitHub's nature of templates](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template), you can fork this repository without inheriting its Git history.
 
 The template starts out very basic, but might receive additional features over time:
 
-- Basic CMake script to build your project and link SFML
+- Basic CMake script to build your project and link SFML on any operating system
 - Basic [GitHub Actions](https://github.com/features/actions) script for all major platforms
 
 ## How to Use
 
 1. Follow the above instructions about how to use GitHub's project template feature to create your own project.
 1. Open [CMakeLists.txt](CMakeLists.txt). Rename the project and the executable to whatever name you want. The project and executable names don't have to match.
-1. Install SFML 2.5.1.
+1. Change the source files listed in [`add_executable`](CMakeLists.txt#L10) to match the source files your project requires.
+1. Configure and build your project. Most popular IDEs support CMake projects with very little effort on your part.
+    - [VS Code](https://code.visualstudio.com) via the [CMake extension](https://code.visualstudio.com/docs/cpp/cmake-linux)
+    - [Visual Studio](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-170)
+    - [CLion](https://www.jetbrains.com/clion/features/cmake-support.html)
+    - [Qt Creator](https://doc.qt.io/qtcreator/creator-project-cmake.html)
 
-    On Ubuntu Linux:
+    Using CMake from the command line is straightforward as well.
+
+    For a single-configuration generator (typically the case on Linux and macOS):
     ```
-    sudo apt install libsfml-dev
+    cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+    cmake --build build
     ```
-    On macOS
+
+    For a multi-configuration generator (typically the case on Windows):
     ```
-    brew install sfml
+    cmake -S . -B build
+    cmake --build build --config Release
     ```
-1. Change the source files listed in [`add_executable`](CMakeLists.txt#L6) to match the source files your project requires.
-1. Configure and build your project.
+1. Enjoy!
 
-   On Linux or macOS, run these commands from the root directory of your project.
-    ```cmake
-    cmake -B build
-    cmake --build build
-    ```
+## Upgrading SFML
 
-    Alternatively, use [VS Code](https://code.visualstudio.com) with its [CMake extension](https://code.visualstudio.com/docs/cpp/cmake-linux) on any OS.
-1. Enjoy!
+SFML is found via CMake's [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) module.
+FetchContent automatically downloads SFML from GitHub and builds it alongside your own code.
+Beyond the convenience of not having to install SFML yourself, this ensures ABI compatability and simplifies things like specifying static versus shared libraries.
+
+Modifying what version of SFML you want is as easy as changing the [`GIT_TAG`](CMakeLists.txt#L7) argument.
+Currently it uses the latest in-development version of SFML 2 via the `2.6.x` tag.
+If you're feeling adventurous and want to give SFML 3 a try, use the `master` tag.
+Beware, this requires changing your code to suit the modified API!
+The nice folks in the [SFML community](https://github.com/SFML/SFML#community) can help you with that transition and the bugs you may encounter along the way.
+
+## But I want to...
+
+Modify CMake options by adding them as configuration parameters (with a `-D` flag) or by modifying the contents of CMakeCache.txt and rebuilding.
+
+### Use Static Libraries
+
+By default SFML builds shared libraries and this default is inherited by your project.
+CMake's [`BUILD_SHARED_LIBS`](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html) option lets you pick static or shared libraries for the entire project.
+
+### Change Compilers
+
+See the variety of [`CMAKE_<LANG>_COMPILER`](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html) options.
+In particular you'll want to modify `CMAKE_CXX_COMPILER` to point to the C++ compiler you wish to use.
+
+### Change Compiler Optimizations
+
+CMake abstracts away specific optimizer flags through the [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) option.
+By default this project recommends `Release` builds which enable optimizations.
+Other build types include `Debug` builds which enable debug symbols but disable optimizations.
+If you're using a multi-configuration generator (as is often the case on Windows), you can modify the [`CMAKE_CONFIGURATION_TYPES`](https://cmake.org/cmake/help/latest/variable/CMAKE_CONFIGURATION_TYPES.html#variable:CMAKE_CONFIGURATION_TYPES) option.
+
+### Change Generators
+
+While CMake will attempt to pick a suitable default generator, some systems offer a number of generators to choose from.
+Ubuntu, for example, offers Makefiles and Ninja as two potential options.
+For a list of generators, click [here](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html).
+To modify the generator you're using you must reconfigure your project providing a `-G` flag with a value corresponding to the generator you want.
+You can't simply modify an entry in the CMakeCache.txt file unlike the above options.
+Then you may rebuild your project with this new generator.
 
 ## More Reading