Update docs for -fuse-ctor-homing

[akhuang]

Summary

Update docs to reflect the fact that this flag is on by default now.

Fixes issue #58367 (https://github.com/llvm/llvm-project/issues/58367).

[dblaikie]

(not sure whether to discuss this here or on the bug)

Should we remove the documentation? Part of the principles of "cc1" flags is that their implementation details, not to be publicly used and maybe not to be publicly documented either?

[akhuang]

In D136188#3866266, @dblaikie wrote:

(not sure whether to discuss this here or on the bug)

Should we remove the documentation? Part of the principles of "cc1" flags is that their implementation details, not to be publicly used and maybe not to be publicly documented either?

That sounds good to me, I guess this paragraph is really only here for "-fno-use-ctor-homing" which doesn't seem like it needs to be documented here.

[akhuang]

Remove documentation paragraph.

[akhuang]

Actually, maybe I should add some of this info to the -fstandalone-debug section.

[dblaikie]

In D136188#3866385, @akhuang wrote:

Actually, maybe I should add some of this info to the -fstandalone-debug section.

Ah, sure, if you like.

At some point I think I/someone should write a full ramble about DWARF type homing in general - I've explained it more than a few times (most often when people hit the "I can't print out a std::string because gdb says something about being unable to find _Rep" - and then after a long-winded explanation/justification, comes down to telling them to install the -dbg or -dev package for libstdc++, basically).

[dblaikie]

(Speaking of which, might be worth pushing on the changes to remove the flags/support for opting out of ctor homing... I know @probinson had some concerns - but I really don't want to end up holding onto the tech debt of these variations & I the original motivation for naming/creating -fstandalone-debug was to have a principled way to decide what goes into this feature and what doesn't - and the rationale for ctor homing is as sound as vtable homing in that regard)

[akhuang]

Move ctor homing info to fstandalone-debug.

[probinson]

+jmorse who is closer to this topic than I am.

We've had a few complaints from licensees about ctor homing, and debug-info size in general is something of a sensitive topic. But if we can come to a place where -fstandalone-debug is an acceptable fallback, I can live with that.

[dblaikie]

Looks good to me with the addition of the forth homing strategy.

In D136188#3866494, @probinson wrote:

+jmorse who is closer to this topic than I am.

We've had a few complaints from licensees about ctor homing, and debug-info size in general is something of a sensitive topic. But if we can come to a place where -fstandalone-debug is an acceptable fallback, I can live with that.

Sounds good (-fstandalone-debug is a pretty big size regression, though, which makes it difficult to swallow) - sorry, didn't mean to derail this review, I should go pick this up again on whatever review I was proposing removing the ctor homing flags/fully rolling it into no-standalone-debug...

clang/docs/UsersManual.rst

2845–2850

There's a forth strategy - clang will emit type definitions for types that are the subject of a explicit template instantiation declarations only in the presence of an explicit instantiation definition for the type.

[akhuang]

Add another debug info strategy to the description

clang/docs/UsersManual.rst

.. option:: -gline-tables-only
   doesn't contain any other data (e.g. description of local variables or
   function parameters).
 
 .. option:: -fstandalone-debug
 
   Clang supports a number of optimizations to reduce the size of debug
   information in the binary. They work based on the assumption that
   the debug type information can be spread out over multiple
-  compilation units.  For instance, Clang will not emit type
-  definitions for types that are not needed by a module and could be
-  replaced with a forward declaration.  Further, Clang will only emit
-  type info for a dynamic C++ class in the module that contains the
-  vtable for the class.
+  compilation units.  Specifically, the optimizations are:
+- will not emit type definitions for types that are not needed by a
+  module and could be replaced with a forward declaration.
+- will only emit type info for a dynamic C++ class in the module that
+  contains the vtable for the class.
+- will only emit type info for a C++ class (non-trivial, non-aggregate)
+  in the modules that contain a definition for one of its constructors.
+- will only emit type definitions for types that are the subject of explicit
+  template instantiation declarations in the presence of an explicit
+  instantiation definition for the type.
 
   The **-fstandalone-debug** option turns off these optimizations.
   This is useful when working with 3rd-party libraries that don't come
   with debug information.  Note that Clang will never emit type
   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. The negation,
-   -fno-use-ctor-homing, ensures that constructor homing is not used.
-
-   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,