From 382459e0478bfefacd0c1c5a0240bd4bab518d53 Mon Sep 17 00:00:00 2001 From: Aaron Loyd Date: Fri, 29 Mar 2024 17:07:38 -0500 Subject: [PATCH] Add section to sanitizer doc for `-Zexternal-clangrt` After spending a week looking for answers to how to do the very thing this flag lets me do, it felt appropriate to document it where I would've expected it to be. --- .../src/compiler-flags/external-clangrt.md | 6 ++++++ .../unstable-book/src/compiler-flags/sanitizer.md | 15 +++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 src/doc/unstable-book/src/compiler-flags/external-clangrt.md diff --git a/src/doc/unstable-book/src/compiler-flags/external-clangrt.md b/src/doc/unstable-book/src/compiler-flags/external-clangrt.md new file mode 100644 index 0000000000000..76b78d733e515 --- /dev/null +++ b/src/doc/unstable-book/src/compiler-flags/external-clangrt.md @@ -0,0 +1,6 @@ +# `external-clangrt` + +This option controls whether the compiler links in its own runtime library for +[sanitizers](./sanitizer.md). Passing this flag makes the compiler *not* link +its own library. For more information, see the section in the sanitizers doc on +[working with other languages.](./sanitizer.md#working-with-other-languages) diff --git a/src/doc/unstable-book/src/compiler-flags/sanitizer.md b/src/doc/unstable-book/src/compiler-flags/sanitizer.md index c8fd154a00ec9..72b44e002b4d4 100644 --- a/src/doc/unstable-book/src/compiler-flags/sanitizer.md +++ b/src/doc/unstable-book/src/compiler-flags/sanitizer.md @@ -45,6 +45,9 @@ To enable a sanitizer compile with `-Zsanitizer=address`, `-Zsanitizer=cfi`, `-Zsanitizer=dataflow`,`-Zsanitizer=hwaddress`, `-Zsanitizer=leak`, `-Zsanitizer=memory`, `-Zsanitizer=memtag`, `-Zsanitizer=shadow-call-stack`, or `-Zsanitizer=thread`. You might also need the `--target` and `build-std` flags. +If you're working with other languages that are also instrumented with sanitizers, +you might need the `external-clangrt` flag. See the section on +[working with other languages](#working-with-other-languages). Example: ```shell @@ -853,6 +856,18 @@ functionality][build-std]. [build-std]: ../../cargo/reference/unstable.html#build-std +# Working with other languages + +Sanitizers rely on compiler runtime libraries to function properly. Rust links +in its own compiler runtime which might conflict with runtimes required by +languages such as C++. Since Rust's runtime doesn't always contain the symbols +required by C++ instrumented code, you might need to skip linking it so another +runtime can be linked instead. + +A separate unstable option `-Zexternal-clangrt` can be used to make rustc skip +linking the compiler runtime for the sanitizer. This will require you to link +in an external runtime, such as from clang instead. + # Build scripts and procedural macros Use of sanitizers together with build scripts and procedural macros is