VISIBILITY

   1 PLEASE READ ALL OF THIS FILE, ESPECIALLY IF YOU ARE DEFINING A NEW
   2 PUBLIC HEADER IN LIBABIGAIL.
   3
   4 How symbols that are exported are controlled in libabigail
   5 ==========================================================
   6
   7 We try to limit the number of ELF symbols that are exported by the
   8 libabigail.so shared library.  We call this symbols visibility
   9 control.
  10
  11 As GNU/Linux is our development platform, we control symbol visibility
  12 by using the visibility support of the G++ compiler.
  13
  14 How to do so is properly explained at https://gcc.gnu.org/wiki/Visibility.
  15
  16 All symbols are hidden by default
  17 =================================
  18
  19 When building translation units that make up the libabigail.so shared
  20 library, G++ is invoked with the -fvisibility=hidden directive.  Which
  21 instructs it to make symbols of functions and global variables
  22 *locally* defined in the shared library, *NOT* exported (or global).
  23
  24 Exporting symbols of entities declared in public headers
  25 ========================================================
  26
  27 In a translation unit that is part of the libabigail.so shared
  28 library, before including a header file that is a public libabigail
  29 header (e.g, abg-ir.h), one need to declare:
  30
  31     #include "abg-internal.h"
  32     ABG_BEGIN_EXPORT_DECLARATIONS
  33
  34 then all the public header files inclusion (using #include directives)
  35 follow.  At the end of these public header files inclusion, one need
  36 to declare:
  37
  38     ABG_END_EXPORT_DECLARATIONS
  39
  40
  41 The ABG_BEGIN_EXPORT_DECLARATIONS is a macro defined in abg-internal.h
  42 which expands to:
  43
  44     #pragma GCC visibility push(default)
  45
  46 This instructs G++ to export the symbol of all global functions and
  47 variables definitions that are declared from that point on.
  48
  49 The ABG_END_EXPORT_DECLARATIONS is a macro defined in abg-internal.h
  50 which expands to:
  51
  52     #pragma GCC visibility pop
  53
  54 It instructs G++ to stop exporting symbols of global functions and
  55 variable definition from that point on.
  56
  57 In practice, the pair ABG_BEGIN_EXPORT_DECLARATIONS,
  58 ABG_END_EXPORT_DECLARATIONS allows us to only export symbols of
  59 global functions and variables declared in the block denoted by these
  60 two macros. Symbols of anything else that is declared outside of that block
  61 are going to be hidden, thanks to the -fvisibility=hidden option
  62 passed to G++.
  63
  64 So whenever you are defining a new header file with declarations that
  65 ought to be part of the API of libabigail, the *definition* file which
  66 defines the declarations of the header file must use
  67 the ABG_BEGIN_EXPORT_DECLARATIONS and ABG_END_EXPORT_DECLARATIONS
  68 macro to include the public header.