Skip to content

Commit a4d29bc

Browse files
committed
Rename build log property
Rename the property that saves the build log, and clarify that the property does not provide a log for a failing build.
1 parent 1099327 commit a4d29bc

File tree

1 file changed

+17
-8
lines changed

1 file changed

+17
-8
lines changed

sycl/doc/extensions/proposed/sycl_ext_oneapi_kernel_compiler.asciidoc

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -266,11 +266,20 @@ _Throws:_
266266

267267
* An `exception` with the `errc::build` error code if the compilation or
268268
linking operations fail.
269-
In this case, the exception `what` string contains a description of the
270-
error.
269+
In this case, the exception `what` string provides a full build log,
270+
including descriptions of any errors, warning messages, and other
271+
diagnostics.
271272
This string is intended for human consumption, and the format may not be
272273
stable across implementations of this extension.
273274

275+
[NOTE]
276+
====
277+
An uncaught `errc::build` exception may result in some or all of the source
278+
code used to create the kernel bundle being printed to the terminal.
279+
In situations where this is undesirable, developers must ensure that the
280+
exception is caught and handled appropriately.
281+
====
282+
274283
Overload (2):
275284

276285
_Constraints:_ Same as overload (1).
@@ -327,14 +336,14 @@ a!
327336
----
328337
namespace sycl::ext::oneapi::experimental {
329338
330-
struct build_log {
339+
struct save_log {
331340
std::string *log;
332-
build_log(std::string *log); (1)
341+
save_log(std::string *to); (1)
333342
};
334-
using build_log_key = build_log;
343+
using save_log_key = save_log;
335344
336345
template<>
337-
struct is_property_key<build_log_key> : std::true_type {};
346+
struct is_property_key<save_log_key> : std::true_type {};
338347
339348
} // namespace sycl::ext::oneapi::experimental {
340349
----
@@ -347,15 +356,15 @@ build.
347356
When a build fails, an `exception` is thrown and the exception's `what` string
348357
provides a description of the error.
349358

350-
Instead, the `build_log` property provides information about a build operation
359+
Instead, the `save_log` property provides information about a build operation
351360
that succeeds.
352361
This might include warning messages or other diagnostics.
353362
Each source language specification can define specific information that is
354363
provided in the log.
355364
In general, the log information is intended for human consumption, and the
356365
format may not be stable across implementations of this extension.
357366

358-
_Effects (1):_ Constructs a `build_log` property with a pointer to a
367+
_Effects (1):_ Constructs a `save_log` property with a pointer to a
359368
`std::string`.
360369
When the `build` function completes successfully, this string will contain the
361370
log.

0 commit comments

Comments
 (0)