Software Engineering

Build Files

Michael L. Collard, Ph.D.

Department of Computer Science, The University of Akron

Creating a Makefile is challenging:

  • Must list all prerequisite include files
  • Straightforward for an in-source build, more difficult for an out-of-source build
  • Note: Out-of-source builds are preferred
  • Make is Turing Complete, but conditional (e.g., if-statements) and repetition (e.g., for-statements) statements have an unfamiliar syntax
  • Limited internal and external libraries and additional support software


  • CMake is a build-file generator and can generate build files for many platforms and environments
  • cmake --help shows a list of Generators
  • Related tools: ctest, cpack
  • Has both command-line and GUI tools
  • Under constant improvement
  • Works well on Linux, macOS, and with Windows MSVC

Build languages are declarative

Abstraction levels get higher over time

  • set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")
  • target_compile_features(${TARGET_NAME} PRIVATE cxx_std_17)
  • More variation, history, and discussion at How to enable C++17 in CMake

There is always more to learn

Multiple structural design decisions to make

  • srcML build file structure
  • Full View
  • Build file structure follows source file tree structure
  • Alternative: A single large CMakeLists.txt that knows the tree structure of the source (and prevents any change to that structure)

Types of CMake Files

  • Full View
  • CMakeLists.txt - The default name, found in the top directory and often in subdirectories
  • CMakePresets.json JSON file with presets to use with the CMake option --preset. Much of the specific build configuration has moved from the CMakeLists.txt into this file.
  • CMakeUserPresets.json JSON file with personal presets to use with the CMake option --preset. It is not committed to the repository, and it is developer-specific.
  • toolchain-gcc CMake commands for a specific platform
  • macos-libarchive.cmake Separates out specific processing from CMakeLists.txt
  • - Input for generating files for other CMake projects to be able to use find_package(srcML) (as with find_package(LibXml2 REQUIRED))
  • CTestConfig.cmake - CDash configuration
  • wix.cpack.cmake CPack configuration for a Windows WiX installer (generates an MSI installer). Custom naming convention so that installers can be loaded automatically.
  • vcpkg.json JSON file with list of dependencies for vcpkg builds. The primary purpose of vcpkg is to easily allow Windows developers to use open-source libraries in their applications. Integrates easily into CMake builds.

Build File Comparison: srcML

File Type File Number LOC
C++ files, C files, ANTLR files 200 (24%) 48 KLOC (38%)
Build Files 40 (5%) 3 KLOC (2%)
Other 525 (70%) 75 KLOC (60%)
Total 768 (100%) 126 KLOC (100%)


  • Always use a build tool to build programs. Do not use direct entry of compiler commands. Build your knowledge into the build file instead of having to remember.
  • Things don't always work the same on all platforms, so you have to experiment
  • While CMake and other tools may be difficult, the main problem is that building code into an executable or installer has many difficult situations
  • In some ways, build files are static and dynamic. They tend to be created and work for a long time but must be maintained as the platforms we build on and for change.