[clang] a1f4e48 - [clang][docs] Add note about using `-flto` with `-g` on macOS

[Jonas Devlieghere via cfe-commits]

Author: Philippe Blain
Date: 2020-06-30T09:33:20-07:00
New Revision: a1f4e48c4aca8c7339be2018926baf860a562f13

URL: https://github.com/llvm/llvm-project/commit/a1f4e48c4aca8c7339be2018926baf860a562f13
DIFF: https://github.com/llvm/llvm-project/commit/a1f4e48c4aca8c7339be2018926baf860a562f13.diff

LOG: [clang][docs] Add note about using `-flto` with `-g` on macOS

If -Wl,object_path_lto,<lto-filename>.o is not passed at link time
when compiling and linking in separate steps with -flto and -g, the
temporary file used for Link Time Optimization is deleted by the linker,
so the executable is missing debug symbols and can't be easily debugged,
and dsymutil can't be run.

Document this behaviour.

Differential revision: https://reviews.llvm.org/D82733

Added: 
    

Modified: 
    clang/docs/CommandGuide/clang.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/CommandGuide/clang.rst b/clang/docs/CommandGuide/clang.rst
index de0e0eda9097..5978650c3288 100644
--- a/clang/docs/CommandGuide/clang.rst
+++ b/clang/docs/CommandGuide/clang.rst
@@ -474,6 +474,16 @@ Code Generation Options
   optimization. With "thin", :doc:`ThinLTO <../ThinLTO>`
   compilation is invoked instead.
 
+  .. note::
+
+     On Darwin, when using :option:`-flto` along with :option:`-g` and
+     compiling and linking in separate steps, you also need to pass
+     ``-Wl,-object_path_lto,<lto-filename>.o`` at the linking step to instruct the
+     ld64 linker not to delete the temporary object file generated during Link
+     Time Optimization (this flag is automatically passed to the linker by Clang
+     if compilation and linking are done in a single step). This allows debugging
+     the executable as well as generating the ``.dSYM`` bundle using :manpage:`dsymutil(1)`.
+
 Driver Options
 ~~~~~~~~~~~~~~