CMake

This page will describe a few tasks that are different for the new CMake build system.

Adding new files to the project

The source files for the project are usually specified in the CMakeLists.txt files which define how a target is built. For the freespace2 and fred2 targets the source files are specified inside the CMakeLists file where the add_executable function is called with the source files as the parameters. Typically this uses a CMake variable for storing the file names. If you want to add a file to these targets you need to add the filename to that variable. File names are always relative to the location of the CMakeLists.txt file.

The code target is organized differently because it uses a lot of files. In the code directory there is a file called source_groups.cmake which contains multiple variables that store the file names. The special thing about this is that these variables are organized according to a folder structure (e.g. the files for the directory ai will be stored in the variable file_root_ai). This is used to create the folder structure inside IDEs such as Visual Studio. If you only want to add a file to an existing folder then you just need to find the right variable and add the file to it.

If you want to add a new folder then you need to do three things:

1. Add a variable with the right name and add the file names
2. Add this variable to the file_root variable at the bottom of the file
3. Add a source_group statement which specifies the folder path in IDEs. The syntax is pretty straight forward, just follow the already existing format.

Default files

Default files are files that are embedded withing the executable so they don't need to exist in a mod. This is used for default table file or GLSL shaders. The files will also be available through CFile so you can use the just like a normal file. CMake changes how these files are handled and adds an automated process for including the files in the executable.

Add new default files

The default file layout follows the standard FSO mod data layout. If you want to add a new file to data/effects then you need to place your file in code/def_files/data/effects. To make CMake actually include the file you also need to edit code/source_groups.cmake. Search for file_root_def_files_data. After that are the files for the individual folders.

If you don't want the file to be available through CFile you can add it to files_root_def_files_builtin.

Change a default file

Just change the contents of the file in code/def_files. The new file content will automatically be included in the executable the next time it is compiled.

Debugging with Visual Studio

Previously it was necessary to change which executable was debugged when using Visual Studio. Now you don't need to do that anymore because the default configuration will use the compiled binary directly. For this to work properly you need to set the FSO_FREESPACE_PATH CMake variable to the path of the directly where your FreeSpace root is located.

Add new external library

Adding external libraries is easier than it was before but the exact procedure depends on the library. Take a look at the existing setups in the lib directory.

Add DLLs on Windows

On Windows it's necessary to copy used DLLs to the binary so they can be found when the executable is run. To automate this task you should use the add_target_copy_files function which accepts multiple paths to files that will be copies to the executable when it is built. This also adds install tasks which will be used when the INSTALL target is built. This will be used by the nightly and release scripts to build the final distribution packages without having to specify those rules twice.

Changing compilation options

There are multiple files in the cmake which affect how the source files are compiled.

The compilation options are separated into platform and compiler options. Platform options are specified in the platform-*.cmake files. These options apply to the whole platform and not just a compiler for that platform. This includes libraries that need to be linked to the executable or special compiler definitions. Those libraries should be linked with the interface library platform which will then be linked with the FSO targets.

The toolchain-*.cmake files contain rules for a family of compilers (e.g. Clang or GCC). This is the place where the actual options should be specified. If a flag may not be supported by all versions of a compiler you can use the CHECK_CXX_COMPILER_FLAG() function to check if the flag is supported. If a compiler needs special libraries or definitions then those should be specified using the compiler interface target.

Setting the project version

The file cmake/version.cmake contains the default version numbers. These can be overwritten when configuring the project. For the revision there are two options:

1. FSO_VERSION_REVISION_STR will specify a generic string for the revision, this can be set to the git hash.
2. FSO_VERSION_REVISION requires an integer and can be set to the CI build number or the nightly build number. These version information will be used to set the name of the executable and also change a few things in the Windows resource files so the generated executables have the right version properties.

Detecting compiler features and version

CMake provides a way of creating a header file that can be used for detecting which compiler is in use, what version of the compiler it is and what C++11 features is supports. This header is written to <BUILD_DIR>/generated_source/scp_compiler_detection.h