[Docs] Add some documentation for constructor homing, a debug info optimization (-fuse-ctor-homing)

[akhuang]

Summary

Adding this, since there's currently no documentation about this.

[dblaikie]

Sounds alright to me.

(non-action idle thoughts: Might be worth revisiting this documentation to make it a bit more direct/clearer that many of these optimizations (at least the vtable and ctor homing) rely on the assumption that the class is instantiated somewhere in the program (and that somewhere is built with debug info enabled) (the wording you've got here "This relies on the additional assumption that all classes that are not trivially constructible have a non-trivial constructor that is used somewhere." but maybe generalized/massaged a bit))

[rnk]

lgtm too

In D95911#2538292, @dblaikie wrote:

(non-action idle thoughts: Might be worth revisiting this documentation to make it a bit more direct/clearer that many of these optimizations (at least the vtable and ctor homing) rely on the assumption that the class is instantiated somewhere in the program (and that somewhere is built with debug info enabled) (the wording you've got here "This relies on the additional assumption that all classes that are not trivially constructible have a non-trivial constructor that is used somewhere." but maybe generalized/massaged a bit))

Yep. While looking at the existing documentation here, I kept thinking we need some standalone documentation on all the debug info features clang supports. There is a lot to cover.

• -gmodules
• -g0, -g1 / -gmlt / -gline-tables-only
• -fstandalone-debug
• this unused types thing
• DWARF versions
• PDBs and codeview
• -fno-inline-line-tables
• various attributes (nomerge, not_tail_called, nodebug/artificial)
• -gcolumn-info
• macro info
• -gcodeview-ghash
• fission / split dwarf
• gdb indexes
• pubnames
• -gz
• debugger tuning gdb/lldb
• others

clang/docs/UsersManual.rst

.. option:: -fstandalone-debug
   information for types that are not referenced at all by the program.
 
 .. option:: -fno-standalone-debug
 
    On Darwin **-fstandalone-debug** is enabled by default. The
    **-fno-standalone-debug** option can be used to get to turn on the
    vtable-based optimization described above.
 
+.. option:: -fuse-ctor-homing
+
+   This optimization is similar to the optimizations that are enabled as part
+   of -fno-standalone-debug. Here, Clang only emits type info for a
+   non-trivial, non-aggregate C++ class in the modules that contain a
+   definition of one of its constructors. This relies on the additional
+   assumption that all classes that are not trivially constructible have a
+   non-trivial constructor that is used somewhere.
+
+   This flag is not enabled by default, and needs to be used with -cc1 or
+   -Xclang.
+
 .. option:: -g
 
   Generate complete debug info.
 
 .. option:: -feliminate-unused-debug-types
 
   By default, Clang does not emit type information for types that are defined
   but not used in a program. To retain the debug info for these unused types,