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

[phil-blain]

Summary

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.

[JDevlieghere]

clang/docs/CommandGuide/clang.rst

477

Any reason not to use the sphinx note directive (.. note:: )?

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#paragraph-level-markup

[phil-blain]

clang/docs/CommandGuide/clang.rst

477

None, appart from my limited knowledge of Sphinx directives ;)

I'll fix that for v2.

[phil-blain]

Use note:: Sphinx directive

Also:

• Fix Sphinx formatting for preformatted text
• Correctly pass the linker argument (initial '-' was missing)

[phil-blain]

I tested the sphinx build for the man and html targets. Any other targets I should check ?

[JDevlieghere]

LGTM. Thank you for adding this!

In D82733#2121414, @phil-blain wrote:

I tested the sphinx build for the man and html targets. Any other targets I should check ?

No, that sounds good.

[phil-blain]

Great, thanks ! Note that I don't have commit access.

clang/docs/CommandGuide/clang.rst

.. option:: -flto, -flto=full, -flto=thin, -emit-llvm
   (which may be passed to the linker depending on the stage selection options).
 
   The default for :option:`-flto` is "full", in which the
   LLVM bitcode is suitable for monolithic Link Time Optimization (LTO), where
   the linker merges all such modules into a single combined module for
   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
 ~~~~~~~~~~~~~~
 
 .. option:: -###
 
   Print (but do not run) the commands to run for this compilation.
 
 .. option:: --help