Lesson 0: CMake

Thu Mar 6, 2014

CMake is really useful for building the lessons since it lets us generate make files or project files for just about any platform and IDE. It also helps with resolving dependencies (such as SDL2), platform specific configurations and much much more. If you’re unfamiliar with CMake there’s a nice introduction available on their site to help you get started.

Windows users: Since Windows doesn't have any standardized include or library directories like Linux and OS X CMake can have some trouble resolving dependencies, so we'll need to give it a hand. I've taken the existing FindSDL2 modules for CMake and have modified them a bit to also check for an environment variable named SDL2. You should create this environment variable and have it point to the root level of the folder containing the SDL2 headers and libraries you downloaded previously.

To lookup SDL2 we’ll need a module to find the dependency we want. Typically these are included in the CMake distribution but for some newer libraries they may not be integrated yet. In the case of SDL2 we’ll need to provide our own module to lookup the dependency. This module is available around online and in the lesson repository. For Windows users I recommend using the modified version from the repository since it will also check for your SDL2 environment variable. The existing FindSDL2.cmake that’s floating around will work for Linux and Mac but will likely fail to find the libraries on Windows.

The CMakeLists.txt Files for Our Project

Our main CMakeLists file needs to do a few things so that we can build our project easily:

  • Append to the CMake module path so we can find our modified SDL2 modules.
  • Set an install directory (called BIN_DIR here) that we can reference for installing our executables.
  • Find SDL2 and add the SDL2 include directory to the include path.
  • Add the Lesson0 subdirectory to find this lesson’s CMakeLists.txt so that we can build it.

This CMakeLists.txt file should be in the top level directory of your project folder for the lessons.

cmake_minimum_required(VERSION 2.6)

# Use our modified FindSDL2* modules
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${TwinklebearDevLessons_SOURCE_DIR}/cmake")
# Set an output directory for our binaries
set(BIN_DIR ${TwinklebearDevLessons_SOURCE_DIR}/bin)

# Bump up warning levels appropriately for clang, gcc & msvc
# Also set debug/optimization flags depending on the build type. IDE users choose this when
# selecting the build mode in their IDE
	set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -pedantic -std=c++11")

# Look up SDL2 and add the include directory to our include path
find_package(SDL2 REQUIRED)

# Look in the Lesson0 subdirectory to find its CMakeLists.txt so we can build the executable

The Test Program

The program we’re building for this lesson is a simple sanity check for SDL. It will initialize the SDL video subsystem, check for any errors and then quit. Our build system will look for this file under Lesson0/src/main.cpp. If you place it elsewhere you’ll need to update the file names and subdirectories in the CMakeLists files.

#include <iostream>
#include <SDL.h>

 * Lesson 0: Test to make sure SDL is setup properly
int main(int, char**){
	if (SDL_Init(SDL_INIT_VIDEO) != 0){
		std::cout << "SDL_Init Error: " << SDL_GetError() << std::endl;
		return 1;
	return 0;

To build our executable for Lesson0 we’ll need another CMakeLists.txt file within the Lesson0 directory, which our main CMakeLists file will check since we’ve added the subdirectory to be searched. Here we just add an executable to be built from our source file and tell CMake to link the executable against the SDL2 libraries. We also add an install target to have the executable be installed to our binary directory.

add_executable(Lesson0 src/main.cpp)
target_link_libraries(Lesson0 ${SDL2_LIBRARY})

If you’ve been using the folder hierarchy used in the lessons you should now have something like this.


Building With CMake

To build the project with CMake we’ll want to make a temporary build directory to store the various build artifacts so we don’t pollute our source directory with a bunch of junk. From this folder we can then run cmake -G "Your Generator" ../ and CMake will generate makefiles or project files for Your Generator. You can run cmake -H to see which generators are available on your system. You can also specify the build type with -DCMAKE_BUILD_TYPE=Type, passing Debug will use the debug flags we set above and likewise for Release. I recommend building with the debug flags since it’ll make it easier to track down problems with your debugger. A sample run of building a Unix Makefiles target in debug mode is shown below.

$ mkdir build && cd build
$ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug ../
$ make
$ make install

In this example regular Unix Makefiles will be generated in the build directory so the project can now be built with make. Running make install will install any targets we’ve specified (our Lesson0 binary) to their install locations (BIN_DIR). Windows users will also need to copy the relevant SDL2.dll to their install directory so that the executables can find it. Be sure to copy the appropriate 32bit or 64bit dll depending on which you built.

End of Lesson 0

When we add more programs throughout the lesson series you can simply add the subdirectory with add_subdirectory(Lesson#) and then re-use the Lesson0 CMakeLists.txt file but replacing the occurances of Lesson0 with Lesson#. When we start adding SDL extension libraries we’ll have to add some more CMake modules and link targets but it’s pretty straightforward to setup.

If you’re having any problems with the lesson please leave a comment below.

I’ll see you again soon in Postscript 0: Properly Finding Resource Paths!