flightgear/docs-mini/README-cmake.md

= CMake in FlightGear overview =

CMake has evolved considerably over the years; if you're reading external tutorials on it, ensure they mention 'modern CMake' since it's very different to the older style.

The top-level CMakeList.txt handles configuration options, finding dependencies, and scanning the rest of the source tree. Across the source tree we add executables, includ 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 original 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 CMakeList.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}")

== Configurations ==

Release builds are built with RelWithDebInfo; this is also the most useful configuration for development, sicne 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.

== Dependencies ==

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

Depending on the dependency, it may supply a Foo-Config.cmake 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 correctly, 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.