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