Rollup merge of #123411 - saethlin:ub-checks, r=Urgau,RalfJung

Put checks that detect UB under their own flag below debug_assertions

Implementation of https://github.com/rust-lang/compiler-team/issues/725

2 files changed, 19 insertions, 1 deletions

diff --git a/src/doc/unstable-book/src/compiler-flags/check-cfg.md b/src/doc/unstable-book/src/compiler-flags/check-cfg.md
index 13027eeaf4f..90a006b0a1e 100644
--- a/src/doc/unstable-book/src/compiler-flags/check-cfg.md
+++ b/src/doc/unstable-book/src/compiler-flags/check-cfg.md
@@ -77,7 +77,7 @@ Those well known names and values follows the same stability as what they refer
 Well known names and values checking is always enabled as long as at least one
 `--check-cfg` argument is present.
 
-As of `2024-02-15T`, the list of known names is as follows:
+As of `2024-04-06T`, the list of known names is as follows:
 
 <!--- See CheckCfg::fill_well_known in compiler/rustc_session/src/config.rs -->
 
@@ -107,6 +107,7 @@ As of `2024-02-15T`, the list of known names is as follows:
  - `target_thread_local`
  - `target_vendor`
  - `test`
+ - `ub_checks`
  - `unix`
  - `windows`
 
diff --git a/src/doc/unstable-book/src/compiler-flags/ub-checks.md b/src/doc/unstable-book/src/compiler-flags/ub-checks.md
new file mode 100644
index 00000000000..528c868d7ad
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-flags/ub-checks.md
@@ -0,0 +1,17 @@
+# `ub-checks`
+
+The tracking issue for this feature is: [#123499](https://github.com/rust-lang/rust/issues/123499).
+
+--------------------
+
+The `-Zub-checks` compiler flag enables additional runtime checks that detect some causes of Undefined Behavior at runtime.
+By default, `-Zub-checks` flag inherits the value of `-Cdebug-assertions`.
+
+All checks are generated on a best-effort basis; even if we have a check implemented for some cause of Undefined Behavior, it may be possible for the check to not fire.
+If a dependency is compiled with `-Zub-checks=no` but the final binary or library is compiled with `-Zub-checks=yes`, UB checks reached by the dependency are likely to be optimized out.
+
+When `-Zub-checks` detects UB, a non-unwinding panic is produced.
+That means that we will not unwind the stack and will not call any `Drop` impls, but we will execute the configured panic hook.
+We expect that unsafe code has been written which relies on code not unwinding which may have UB checks inserted.
+Ergo, an unwinding panic could easily turn works-as-intended UB into a much bigger problem.
+Calling the panic hook theoretically has the same implications, but we expect that the standard library panic hook will be stateless enough to be always called, and that if a user has configured a panic hook that the hook may be very helpful to debugging the detected UB.