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