flightgear/docs-mini/README-cmake.md

CMake in FlightGear overview

CMake has evolved considerably in the past decade; if you're reading external tutorials abput it, ensure they mention 'modern CMake', or the information will be incorrect.

The top-level CMakeLists.txt handles configuration options, finding dependencies, and scanning the rest of the source tree. Across the source tree we add executables, including the main FGFS binary but also other helpers and utilities. We also define targets for helper libraries, for various reasons; for example to build some code with different include paths or flags.

Due to the historical code structure, we use some helper functions to collect most of the application sources into two global CMake variables, which are then read and added to the main executable target, in src/Main/CMakeList.txt. Therefore, many subdirectories have a trivial CMakeLists.txt which simply calls the helper functions to add its sources:

include(FlightGearComponent)

set(SOURCES
	foo.cxx
	bar.cxx
	)

set(HEADERS
	foo.hxx
	bar.hxx
	)
    	
flightgear_component(MyComp "${SOURCES}" "${HEADERS}")

The global properties used are FG_SOURCES and FG_HEADERS.

Configurations

Official release builds are built with RelWithDebInfo; this is also the most useful configuration for development, since on Windows, Debug is unusably slow. If trying to optimise performance, keep in mind that compiler flags must be manually set for RelWithDebInfo; they are not automatically inherited from Release.

Adding additional configurations is possible: for example for profiling. CMake also picks up the CXXFLAGS environment variable to pass ad-hoc compiler options, without modifying the build systen.

Dependencies

All dependencies should be handled via an IMPORTED target: this ensures that include paths, link options, etc specific to the dependency are handled correctly across different platforms.

For some dependencies, there may be a zFoo-Config.cmakez which defines such a target for you automatically. Or there may be an existing FindFoo.cmake which does the same. If neither of these situations exist, create a custom finder file in CMakeModules, following the existing examples.

CMake tracks transitive dependencies precisely, so for example if your new dependency is used in SimGear, it will automatically be added to the include / link paths for FlightGear based on the SimGear build type.

If you encounter a case where a downstream target is missing an include path or flag for a dependency, it typically indicates a bug in your dependency graph. Do not fix it by maanually modifying the downstream target's include path or flags. Rather, fix your dependency graph and/or INTERFACE exports from your dependency, so that CMake can see the required transitive dependencies correctly.