cmake-configure-log - Man Page

Each of the Event Kinds is versioned independently.  The set of keys an event's log entry provides is specific to its major version. When an event is logged, the latest version of its event kind that is known to the running version of CMake is always written to the log.

Tools reading the configure log must ignore event kinds and versions they do not understand:

• A future version of CMake may introduce a new event kind or version.
• If an existing build tree is re-configured with a different version of CMake, the log may contain different versions of the same event kind.
• If cmake-file-api(7) queries request one or more configureLog object versions, the log may contain multiple entries for the same event, each with a different version of its event kind.

IDEs should write a cmake-file-api(7) query requesting a specific configureLog object version, before running CMake, and then read the configure log only as described by the file-api reply.

In order to make the log human-readable, text blocks are always represented using YAML literal block scalars (|). Since literal block scalars do not support escaping, backslashes and non-printable characters are encoded at the application layer:

• \\ encodes a backslash.
• \xXX encodes a byte using two hexadecimal digits, XX.

The message(CONFIGURE_LOG) command logs message events.

There is only one message event major version, version 1.

A message-v1 event is a YAML mapping:

kind: "message-v1"
backtrace:
  - "CMakeLists.txt:123 (message)"
checks:
  - "Checking for something"
message: |
  # ...

The keys specific to message-v1 mappings are:

message

A YAML literal block scalar containing the message text, represented using our Text Block Encoding.

The try_compile() command logs try_compile events.

There is only one try_compile event major version, version 1.

A try_compile-v1 event is a YAML mapping:

kind: "try_compile-v1"
backtrace:
  - "CMakeLists.txt:123 (try_compile)"
checks:
  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:
  source: "/path/to/.../TryCompile-01234"
  binary: "/path/to/.../TryCompile-01234"
cmakeVariables:
  SOME_VARIABLE: "Some Value"
buildResult:
  variable: "COMPILE_RESULT"
  cached: true
  stdout: |
    # ...
  exitCode: 0

The keys specific to try_compile-v1 mappings are:

description

An optional key that is present when the LOG_DESCRIPTION <text> option was used.  Its value is a string containing the description <text>.

directories

A mapping describing the directories associated with the compilation attempt.  It has the following keys:

source

String specifying the source directory of the try_compile() project.

binary

String specifying the binary directory of the try_compile() project. For non-project invocations, this is often the same as the source directory.

cmakeVariables

An optional key that is present when CMake propagates variables into the test project, either automatically or due to the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable. Its value is a mapping from variable names to their values.

buildResult

A mapping describing the result of compiling the test code. It has the following keys:

variable

A string specifying the name of the CMake variable storing the result of trying to build the test project.

cached

A boolean indicating whether the above result variable is stored in the CMake cache.

stdout

A YAML literal block scalar containing the output from building the test project, represented using our Text Block Encoding. This contains build output from both stdout and stderr.

exitCode

An integer specifying the build tool exit code from trying to build the test project.

The try_run() command logs try_run events.

There is only one try_run event major version, version 1.

A try_run-v1 event is a YAML mapping:

kind: "try_run-v1"
backtrace:
  - "CMakeLists.txt:456 (try_run)"
checks:
  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:
  source: "/path/to/.../TryCompile-56789"
  binary: "/path/to/.../TryCompile-56789"
buildResult:
  variable: "COMPILE_RESULT"
  cached: true
  stdout: |
    # ...
  exitCode: 0
runResult:
  variable: "RUN_RESULT"
  cached: true
  stdout: |
    # ...
  stderr: |
    # ...
  exitCode: 0

The keys specific to try_run-v1 mappings include those documented by the try_compile-v1 event, plus:

runResult

A mapping describing the result of running the test code. It has the following keys:

variable

A string specifying the name of the CMake variable storing the result of trying to run the test executable.

cached

A boolean indicating whether the above result variable is stored in the CMake cache.

stdout

An optional key that is present when the test project built successfully. Its value is a YAML literal block scalar containing output from running the test executable, represented using our Text Block Encoding.

If RUN_OUTPUT_VARIABLE was used, stdout and stderr are captured together, so this will contain both.  Otherwise, this will contain only the stdout output.

stderr

An optional key that is present when the test project built successfully and the RUN_OUTPUT_VARIABLE option was not used. Its value is a YAML literal block scalar containing output from running the test executable, represented using our Text Block Encoding.

If RUN_OUTPUT_VARIABLE was used, stdout and stderr are captured together in the stdout key, and this key will not be present. Otherwise, this will contain the stderr output.

exitCode

An optional key that is present when the test project built successfully. Its value is an integer specifying the exit code, or a string containing an error message, from trying to run the test executable.