1============== 2LTO Visibility 3============== 4 5*LTO visibility* is a property of an entity that specifies whether it can be 6referenced from outside the current LTO unit. A *linkage unit* is a set of 7translation units linked together into an executable or DSO, and a linkage 8unit's *LTO unit* is the subset of the linkage unit that is linked together 9using link-time optimization; in the case where LTO is not being used, the 10linkage unit's LTO unit is empty. Each linkage unit has only a single LTO unit. 11 12The LTO visibility of a class is used by the compiler to determine which 13classes the virtual function call optimization and control flow integrity 14features apply to. These features use whole-program information, so they 15require the entire class hierarchy to be visible in order to work correctly. 16 17If any translation unit in the program uses either of the virtual function 18call optimization or control flow integrity features, it is effectively an 19ODR violation to define a class with hidden LTO visibility in multiple linkage 20units. A class with public LTO visibility may be defined in multiple linkage 21units, but the tradeoff is that the virtual function call optimization and 22control flow integrity features can only be applied to classes with hidden LTO 23visibility. A class's LTO visibility is treated as an ODR-relevant property 24of its definition, so it must be consistent between translation units. 25 26In translation units built with LTO, LTO visibility is based on the 27class's symbol visibility as expressed at the source level (i.e. the 28``__attribute__((visibility("...")))`` attribute, or the ``-fvisibility=`` 29flag) or, on the Windows platform, the dllimport and dllexport attributes. When 30targeting non-Windows platforms, classes with a visibility other than hidden 31visibility receive public LTO visibility. When targeting Windows, classes 32with dllimport or dllexport attributes receive public LTO visibility. All 33other classes receive hidden LTO visibility. Classes with internal linkage 34(e.g. classes declared in unnamed namespaces) also receive hidden LTO 35visibility. 36 37A class defined in a translation unit built without LTO receives public 38LTO visibility regardless of its object file visibility, linkage or other 39attributes. 40 41This mechanism will produce the correct result in most cases, but there are 42two cases where it may wrongly infer hidden LTO visibility. 43 441. As a corollary of the above rules, if a linkage unit is produced from a 45 combination of LTO object files and non-LTO object files, any hidden 46 visibility class defined in both a translation unit built with LTO and 47 a translation unit built without LTO must be defined with public LTO 48 visibility in order to avoid an ODR violation. 49 502. Some ABIs provide the ability to define an abstract base class without 51 visibility attributes in multiple linkage units and have virtual calls 52 to derived classes in other linkage units work correctly. One example of 53 this is COM on Windows platforms. If the ABI allows this, any base class 54 used in this way must be defined with public LTO visibility. 55 56Classes that fall into either of these categories can be marked up with the 57``[[clang::lto_visibility_public]]`` attribute. To specifically handle the 58COM case, classes with the ``__declspec(uuid())`` attribute receive public 59LTO visibility. On Windows platforms, clang-cl's ``/MT`` and ``/MTd`` 60flags statically link the program against a prebuilt standard library; 61these flags imply public LTO visibility for every class declared in the 62``std`` and ``stdext`` namespaces. 63 64Example 65======= 66 67The following example shows how LTO visibility works in practice in several 68cases involving two linkage units, ``main`` and ``dso.so``. 69 70.. code-block:: none 71 72 +-----------------------------------------------------------+ +----------------------------------------------------+ 73 | main (clang++ -fvisibility=hidden): | | dso.so (clang++ -fvisibility=hidden): | 74 | | | | 75 | +-----------------------------------------------------+ | | struct __attribute__((visibility("default"))) C { | 76 | | LTO unit (clang++ -fvisibility=hidden -flto): | | | virtual void f(); | 77 | | | | | } | 78 | | struct A { ... }; | | | void C::f() {} | 79 | | struct [[clang::lto_visibility_public]] B { ... }; | | | struct D { | 80 | | struct __attribute__((visibility("default"))) C { | | | virtual void g() = 0; | 81 | | virtual void f(); | | | }; | 82 | | }; | | | struct E : D { | 83 | | struct [[clang::lto_visibility_public]] D { | | | virtual void g() { ... } | 84 | | virtual void g() = 0; | | | }; | 85 | | }; | | | __attribute__(visibility("default"))) D *mkE() { | 86 | | | | | return new E; | 87 | +-----------------------------------------------------+ | | } | 88 | | | | 89 | struct B { ... }; | +----------------------------------------------------+ 90 | | 91 +-----------------------------------------------------------+ 92 93We will now describe the LTO visibility of each of the classes defined in 94these linkage units. 95 96Class ``A`` is not defined outside of ``main``'s LTO unit, so it can have 97hidden LTO visibility. This is inferred from the object file visibility 98specified on the command line. 99 100Class ``B`` is defined in ``main``, both inside and outside its LTO unit. The 101definition outside the LTO unit has public LTO visibility, so the definition 102inside the LTO unit must also have public LTO visibility in order to avoid 103an ODR violation. 104 105Class ``C`` is defined in both ``main`` and ``dso.so`` and therefore must 106have public LTO visibility. This is correctly inferred from the ``visibility`` 107attribute. 108 109Class ``D`` is an abstract base class with a derived class ``E`` defined 110in ``dso.so``. This is an example of the COM scenario; the definition of 111``D`` in ``main``'s LTO unit must have public LTO visibility in order to be 112compatible with the definition of ``D`` in ``dso.so``, which is observable 113by calling the function ``mkE``. 114