Step 7: Custom Commands and Generated Files

Code generation is a ubiquitous mechanism for extending programming languages beyond the bounds of their language model. CMake has first-class support for Qt's Meta-Object Compiler, but very few other code generators are notable enough to warrant that kind of effort.

Instead, code generators tend to be bespoke and usage specific. CMake provides facilities for describing the usage of a code generator, so projects can add support for their individual needs.

In this step, we will use add_custom_command() to add support for a code generator within the tutorial project.

Background

Any step in the build process can generally be described in terms of its inputs and outputs. CMake assumes that code generators and other custom processes operate on the same principle. In this way, the code generator acts identically to compilers, linkers, and other elements of the toolchain; when the inputs are newer than the outputs (or the outputs don't exist), a user-specified command will be run to update the outputs.

Note

This model assumes the outputs of a process are known before it is run. CMake lacks the ability to describe code generators where the name and location of the outputs depends on the content of the input. Various hacks exist to shim this functionality into CMake, but they are outside the scope of this tutorial.

Describing a code generator (or any custom process) is usually performed in two parts. First, the inputs and outputs are described independently of the CMake target model, concerned only with the generation process itself. Second, the outputs are associated with a CMake target to insert them into the CMake target model.

For sources, this is as simple as adding the generated files to the source list of a STATIC, SHARED, or OBJECT library. For header-only generators, it's often necessary to use an intermediary target created via add_custom_target() to add the header file generation to the build stage (because INTERFACE libraries have no build step).

Exercise 1 - Using a Code Generator

The primary mechanism for describing a code generator is the add_custom_command() command. A "command", for the purpose of add_custom_command() is either an executable available in the build environment or a CMake executable target name.

add_executable(Tool)
# ...
add_custom_command(
  OUTPUT Generated.cxx
  COMMAND Tool -i input.txt -o Generated.cxx
  DEPENDS Tool input.txt
  VERBATIM
)
# ...
add_library(GeneratedObject OBJECT)
target_sources(GeneratedObject
  PRIVATE
    Generated.cxx
)

Most of the keywords are self-explanatory, with the exception of VERBATIM. This argument is effectively mandatory for legacy reasons that are uninteresting to explain in a modern context. The curious should consult the add_custom_command() documentation for additional details.

The Tool executable target appears both in the COMMAND and DEPENDS parameters. While COMMAND is sufficient for the code to build correctly, adding the Tool itself as a dependency of the custom command ensure that if Tool is updated, the custom command will be rerun.

For header-only file generation, additional commands are necessary because the library itself has no build step. We can use add_custom_target() to create an "artificial" build step for the library. We then force the custom target to be run before any targets which link the library with the command add_dependencies().

add_custom_target(RunGenerator DEPENDS Generated.h)

add_library(GeneratedLib INTERFACE)
target_sources(GeneratedLib
  INTERFACE
    FILE_SET HEADERS
    BASE_DIRS
      ${CMAKE_CURRENT_BINARY_DIR}
    FILES
      ${CMAKE_CURRENT_BINARY_DIR}/Generated.h
)

add_dependencies(GeneratedLib RunGenerator)

Note

We add the CMAKE_CURRENT_BINARY_DIR, a variable which names the current location in the build tree where our artifacts are being placed, to the base directories because that's the working directory our code generator will be run inside of. Listing the FILES is unnecessary for the build and done so here only for clarity.

Goal

Add a generated table of pre-computed square roots to the MathFunctions library.

Helpful Resources

Files to Edit

  • MathFunctions/CMakeLists.txt

  • MathFunctions/MakeTable/CMakeLists.txt

  • MathFunctions/MathFunctions.cxx

Getting Started

The MathFunctions library has been edited to use a pre-computed table when given a number less than 10. However, the hardcoded table is not particularly accurate, containing only the nearest truncated integer value.

The MakeTable.cxx source file describes a program which will generate a better table. It takes a single argument as input, the file name of the table to be generated.

Complete TODO 1 through TODO 10.

Build and Run

No special configuration is needed, configure and build as usual. Note that the MakeTable executable is sequenced before MathFunctions.

cmake --preset tutorial
cmake --build build

Verify the output of Tutorial now uses the pre-computed table for values less than 10.

Solution

First we add a new executable to generate the tables, adding the MakeTable.cxx file as a source.

TODO 1-2: Click to show/hide answer
TODO 1-2: MathFunctions/MakeTable/CMakeLists.txt
add_executable(MakeTable)

target_sources(MakeTable
  PRIVATE
    MakeTable.cxx
)

Then we add a custom command which produces the table, and custom target which depends on the table.

TODO 3-4: Click to show/hide answer
TODO 3-4: MathFunctions/MakeTable/CMakeLists.txt
add_custom_command(
  OUTPUT SqrtTable.h
  COMMAND MakeTable SqrtTable.h
  DEPENDS MakeTable
  VERBATIM
)

add_custom_target(RunMakeTable DEPENDS SqrtTable.h)

We need to add an interface library which describes the output which will appear in CMAKE_CURRENT_BINARY_DIR. The FILES parameter is optional.

TODO 5-6: Click to show/hide answer
TODO 5-6: MathFunctions/MakeTable/CMakeLists.txt
add_library(SqrtTable INTERFACE)

target_sources(SqrtTable
  INTERFACE
    FILE_SET HEADERS
    BASE_DIRS
      ${CMAKE_CURRENT_BINARY_DIR}
    FILES
      ${CMAKE_CURRENT_BINARY_DIR}/SqrtTable.h
)

Now that all the targets are described, we can force the custom target to run before any dependents of the interface library by associating them with add_dependencies().

TODO 7: Click to show/hide answer
TODO 7: MathFunctions/MakeTable/CMakeLists.txt
add_dependencies(SqrtTable RunMakeTable)

We are ready to add the interface library to the linked libraries of MathFunctions, and add the entire MakeTable folder to the project.

TODO 8-9: Click to show/hide answer
TODO 9: MathFunctions/CMakeLists.txt
add_subdirectory(MakeTable)

Finally, we update the MathFunctions library itself to take advantage of the generated table.

TODO 10: Click to show/hide answer
TODO 10: MathFunctions/MathFunctions.cxx
#include <SqrtTable.h>

double table_sqrt(double x)
{