[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

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
 ~~~~~~~~~~~~~~