1CMAKE-CONFIGURE-LOG(7) CMake CMAKE-CONFIGURE-LOG(7)
2
6 cmake-configure-log - CMake Configure Log
7 New in version 3.26.
9
12 CMake writes a running log, known as the configure log, of certain
13 events that occur during the Configure step. The configure log does
14 not contain a log of all output, errors, or messages printed while con‐
15 figuring a project. It is a log of detailed information about specific
16 events, such as toolchain inspection by try_compile(), meant for use in
17 debugging the configuration of a build tree.
18 For human use, this version of CMake writes the configure log to the
20 file:
21 ${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml
23 However, the location and name of the log file may change in future
25 versions of CMake. Tools that read the configure log should get its
26 location using a configureLog query to the cmake-file-api(7). See the
27 Log Versioning section below for details.
28
30 The configure log is designed to be both machine- and human-readable.
31 The log file is a YAML document stream containing zero or more YAML
33 documents separated by document markers. Each document begins with a
34 --- document marker line, contains a single YAML mapping that logs
35 events from one CMake "configure" step, and, if the configure step fin‐
36 ished normally, ends with a ... document marker line:
37 ---
39 events:
40 -
41 kind: "try_compile-v1"
42 # (other fields omitted)
43 -
44 kind: "try_compile-v1"
45 # (other fields omitted)
46 ...
47 A new document is appended to the log every time CMake configures the
49 build tree and logs new events.
50 The keys of the each document root mapping are:
52 events A YAML block sequence of nodes corresponding to events logged
54 during one CMake "configure" step. Each event is a YAML node
55 containing one of the Event Kinds documented below.
56 Log Versioning
58 Each of the Event Kinds is versioned independently. The set of keys an
59 event's log entry provides is specific to its major version. When an
60 event is logged, the latest version of its event kind that is known to
61 the running version of CMake is always written to the log.
62 Tools reading the configure log must ignore event kinds and versions
64 they do not understand:
65 • A future version of CMake may introduce a new event kind or version.
67 • If an existing build tree is re-configured with a different version
69 of CMake, the log may contain different versions of the same event
70 kind.
71 • If cmake-file-api(7) queries request one or more configureLog object
73 versions, the log may contain multiple entries for the same event,
74 each with a different version of its event kind.
75 IDEs should write a cmake-file-api(7) query requesting a specific
77 configureLog object version, before running CMake, and then read the
78 configure log only as described by the file-api reply.
79 Text Block Encoding
81 In order to make the log human-readable, text blocks are always repre‐
82 sented using YAML literal block scalars (|). Since literal block
83 scalars do not support escaping, backslashes and non-printable charac‐
84 ters are encoded at the application layer:
85 • \\ encodes a backslash.
87 • \xXX encodes a byte using two hexadecimal digits, XX.
89
91 Every event kind is represented by a YAML mapping of the form:
92 kind: "<kind>-v<major>"
94 backtrace:
95 - "<file>:<line> (<function>)"
96 checks:
97 - "Checking for something"
98 #...event-specific keys...
99 The keys common to all events are:
101 kind A string identifying the event kind and major version.
103 backtrace
105 A YAML block sequence reporting the call stack of CMake source
106 locations at which the event occurred, from most-recent to
107 least-recent. Each node is a string specifying one location
108 formatted as <file>:<line> (<function>).
109 checks An optional key that is present when the event occurred with at
111 least one pending message(CHECK_START). Its value is a YAML
112 block sequence reporting the stack of pending checks, from
113 most-recent to least-recent. Each node is a string containing a
114 pending check message.
115 Additional mapping keys are specific to each (versioned) event kind,
117 described below.
118 Event Kind message
120 The message(CONFIGURE_LOG) command logs message events.
121 There is only one message event major version, version 1.
123 message-v1 Event
125 A message-v1 event is a YAML mapping:
126 kind: "message-v1"
128 backtrace:
129 - "CMakeLists.txt:123 (message)"
130 checks:
131 - "Checking for something"
132 message: |
133 # ...
134 The keys specific to message-v1 mappings are:
136 message
138 A YAML literal block scalar containing the message text, repre‐
139 sented using our Text Block Encoding.
140 Event Kind try_compile
142 The try_compile() command logs try_compile events.
143 There is only one try_compile event major version, version 1.
145 try_compile-v1 Event
147 A try_compile-v1 event is a YAML mapping:
148 kind: "try_compile-v1"
150 backtrace:
151 - "CMakeLists.txt:123 (try_compile)"
152 checks:
153 - "Checking for something"
154 description: "Explicit LOG_DESCRIPTION"
155 directories:
156 source: "/path/to/.../TryCompile-01234"
157 binary: "/path/to/.../TryCompile-01234"
158 cmakeVariables:
159 SOME_VARIABLE: "Some Value"
160 buildResult:
161 variable: "COMPILE_RESULT"
162 cached: true
163 stdout: |
164 # ...
165 exitCode: 0
166 The keys specific to try_compile-v1 mappings are:
168 description
170 An optional key that is present when the LOG_DESCRIPTION <text>
171 option was used. Its value is a string containing the descrip‐
172 tion <text>.
173 directories
175 A mapping describing the directories associated with the compi‐
176 lation attempt. It has the following keys:
177 source String specifying the source directory of the
179 try_compile() project.
180 binary String specifying the binary directory of the
182 try_compile() project. For non-project invocations, this
183 is often the same as the source directory.
184 cmakeVariables
186 An optional key that is present when CMake propagates variables
187 into the test project, either automatically or due to the
188 CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable. Its value is a
189 mapping from variable names to their values.
190 buildResult
192 A mapping describing the result of compiling the test code. It
193 has the following keys:
194 variable
196 A string specifying the name of the CMake variable stor‐
197 ing the result of trying to build the test project.
198 cached A boolean indicating whether the above result variable is
200 stored in the CMake cache.
201 stdout A YAML literal block scalar containing the output from
203 building the test project, represented using our Text
204 Block Encoding. This contains build output from both
205 stdout and stderr.
206 exitCode
208 An integer specifying the build tool exit code from try‐
209 ing to build the test project.
210 Event Kind try_run
212 The try_run() command logs try_run events.
213 There is only one try_run event major version, version 1.
215 try_run-v1 Event
217 A try_run-v1 event is a YAML mapping:
218 kind: "try_run-v1"
220 backtrace:
221 - "CMakeLists.txt:456 (try_run)"
222 checks:
223 - "Checking for something"
224 description: "Explicit LOG_DESCRIPTION"
225 directories:
226 source: "/path/to/.../TryCompile-56789"
227 binary: "/path/to/.../TryCompile-56789"
228 buildResult:
229 variable: "COMPILE_RESULT"
230 cached: true
231 stdout: |
232 # ...
233 exitCode: 0
234 runResult:
235 variable: "RUN_RESULT"
236 cached: true
237 stdout: |
238 # ...
239 stderr: |
240 # ...
241 exitCode: 0
242 The keys specific to try_run-v1 mappings include those documented by
244 the try_compile-v1 event, plus:
245 runResult
247 A mapping describing the result of running the test code. It
248 has the following keys:
249 variable
251 A string specifying the name of the CMake variable stor‐
252 ing the result of trying to run the test executable.
253 cached A boolean indicating whether the above result variable is
255 stored in the CMake cache.
256 stdout An optional key that is present when the test project
258 built successfully. Its value is a YAML literal block
259 scalar containing output from running the test exe‐
260 cutable, represented using our Text Block Encoding.
261 If RUN_OUTPUT_VARIABLE was used, stdout and stderr are
263 captured together, so this will contain both. Otherwise,
264 this will contain only the stdout output.
265 stderr An optional key that is present when the test project
267 built successfully and the RUN_OUTPUT_VARIABLE option was
268 not used. Its value is a YAML literal block scalar con‐
269 taining output from running the test executable, repre‐
270 sented using our Text Block Encoding.
271 If RUN_OUTPUT_VARIABLE was used, stdout and stderr are
273 captured together in the stdout key, and this key will
274 not be present. Otherwise, this will contain the stderr
275 output.
276 exitCode
278 An optional key that is present when the test project
279 built successfully. Its value is an integer specifying
280 the exit code, or a string containing an error message,
281 from trying to run the test executable.
282
284 2000-2023 Kitware, Inc. and Contributors
2853.27.7 Oct 07, 2023 CMAKE-CONFIGURE-LOG(7)