diff --git a/CONTRIBUTING b/CONTRIBUTING index 2796abc4..0b0f9044 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -30,6 +30,11 @@ Patches have to be sent by email to libabigail@sourceware.org. Please read the file COMMIT-LOG-GUIDELINES in the source tree to learn about how to write the commit log accompanying the patch. +If you are adding a new public header file to the project, or if you +are defining a new entry point to the API of libabigail, please take +some time to read the file VISIBILITY about how you need to handle the +visibility of symbols that are part of the API and ABI of libabigail. + Make sure you sign your patch. To learn about signing, please read the "Sign your work" chapter below. diff --git a/Makefile.am b/Makefile.am index 6e2a32f9..9d2876df 100644 --- a/Makefile.am +++ b/Makefile.am @@ -19,8 +19,9 @@ EXTRA_DIST = \ autoconf-archive/ax_check_python_modules.m4 \ autoconf-archive/ax_prog_python_version.m4 \ autoconf-archive/ax_compare_version.m4 \ -NEWS README COPYING ChangeLog \ -COPYING-LGPLV2 COPYING-LGPLV3 \ +NEWS README COPYING COMPILING \ +COMMIT-LOG-GUIDELINES VISIBILITY \ +ChangeLog COPYING-LGPLV2 COPYING-LGPLV3 \ COPYING-GPLV3 gen-changelog.py \ $(headers) $(m4data_DATA) \ libabigail.pc.in diff --git a/VISIBILITY b/VISIBILITY new file mode 100644 index 00000000..b78111be --- /dev/null +++ b/VISIBILITY @@ -0,0 +1,68 @@ +PLEASE READ ALL OF THIS FILE, ESPECIALLY IF YOU ARE DEFINING A NEW +PUBLIC HEADER IN LIBABIGAIL. + +How symbols that are exported are controlled in libabigail +========================================================== + +We try to limit the number of ELF symbols that are exported by the +libabigail.so shared library. We call this symbols visibility +control. + +As GNU/Linux is our development platform, we control symbol visibility +by using the visibility support of the G++ compiler. + +How to do so is properly explained at https://gcc.gnu.org/wiki/Visibility. + +All symbols are hidden by default +================================= + +When building translation units that make up the libabigail.so shared +library, G++ is invoked with the -fvisibility=hidden directive. Which +instructs it to make symbols of functions and global variables +*locally* defined in the shared library, *NOT* exported (or global). + +Exporting symbols of entities declared in public headers +======================================================== + +In a translation unit that is part of the libabigail.so shared +library, before including a header file that is a public libabigail +header (e.g, abg-ir.h), one need to declare: + + #include "abg-internal.h" + ABG_BEGIN_EXPORT_DECLARATIONS + +then all the public header files inclusion (using #include directives) +follow. At the end of these public header files inclusion, one need +to declare: + + ABG_END_EXPORT_DECLARATIONS + + +The ABG_BEGIN_EXPORT_DECLARATIONS is a macro defined in abg-internal.h +which expands to: + + #pragma GCC visibility push(default) + +This instructs G++ to export the symbol of all global functions and +variables definitions that are declared from that point on. + +The ABG_END_EXPORT_DECLARATIONS is a macro defined in abg-internal.h +which expands to: + + #pragma GCC visibility pop + +It instructs G++ to stop exporting symbols of global functions and +variable definition from that point on. + +In practice, the pair ABG_BEGIN_EXPORT_DECLARATIONS, +ABG_END_EXPORT_DECLARATIONS allows us to only export symbols of +global functions and variables declared in the block denoted by these +two macros. Symbols of anything else that is declared outside of that block +are going to be hidden, thanks to the -fvisibility=hidden option +passed to G++. + +So whenever you are defining a new header file with declarations that +ought to be part of the API of libabigail, the *definition* file which +defines the declarations of the header file must use +the ABG_BEGIN_EXPORT_DECLARATIONS and ABG_END_EXPORT_DECLARATIONS +macro to include the public header. diff --git a/configure.ac b/configure.ac index 84f423ad..eb9caebc 100644 --- a/configure.ac +++ b/configure.ac @@ -134,10 +134,14 @@ if test x$SUPPORTS_GCC_VISIBILITY_ATTRIBUTE = xyes; then AC_MSG_NOTICE([GCC visibility attribute is supported]) AC_DEFINE([HAS_GCC_VISIBILITY_ATTRIBUTE], 1, [Defined if the compiler supports the attribution visibility syntax __attribute__((visibility("hidden")))]) + VISIBILITY_FLAGS="-fvisibility=hidden" else AC_MSG_NOTICE([GCC visibility attribute is not supported]) + VISIBILITY_FLAGS= fi +AC_SUBST(VISIBILITY_FLAGS) + dnl Check for dependency: libelf, libdw, libebl (elfutils) dnl Note that we need to use at least elfutils 0.159 but dnl at that time elfutils didnt have pkgconfig capabilities diff --git a/src/Makefile.am b/src/Makefile.am index b7adc24e..7b5156ca 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -1,11 +1,13 @@ lib_LTLIBRARIES=libabigail.la libabigaildir=$(libdir) +AM_CXXFLAGS = $(VISIBILITY_FLAGS) + if ENABLE_CXX11 CXX11_SOURCES = abg-viz-common.cc \ abg-viz-dot.cc \ abg-viz-svg.cc -AM_CXXFLAGS="-std=gnu++11" +AM_CXXFLAGS += "-std=gnu++11" else CXX11_SOURCES = endif diff --git a/src/abg-comp-filter.cc b/src/abg-comp-filter.cc index de89f1b0..62c62139 100644 --- a/src/abg-comp-filter.cc +++ b/src/abg-comp-filter.cc @@ -1,6 +1,6 @@ // -*- Mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -25,8 +25,15 @@ /// This file contains definitions of diff objects filtering /// facilities. +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-comp-filter.h" +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { namespace comparison diff --git a/src/abg-comparison.cc b/src/abg-comparison.cc index 0243f3ca..9f1dec72 100644 --- a/src/abg-comparison.cc +++ b/src/abg-comparison.cc @@ -26,15 +26,23 @@ /// libabigail. #include +#include #include #include -#include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-hash.h" #include "abg-suppression.h" #include "abg-comp-filter.h" #include "abg-sptr-utils.h" #include "abg-tools-utils.h" +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-config.cc b/src/abg-config.cc index 8b1f7eb2..88e54652 100644 --- a/src/abg-config.cc +++ b/src/abg-config.cc @@ -1,6 +1,6 @@ // -*- Mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -20,10 +20,16 @@ /// @file -#include "config.h" +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-config.h" #include "abg-version.h" +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { config::config() diff --git a/src/abg-corpus.cc b/src/abg-corpus.cc index 465d960b..891ca27b 100644 --- a/src/abg-corpus.cc +++ b/src/abg-corpus.cc @@ -28,6 +28,11 @@ #include #include #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-sptr-utils.h" #include "abg-ir.h" #include "abg-corpus.h" @@ -38,6 +43,9 @@ #include "abg-libzip-utils.h" #endif +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-diff-utils.cc b/src/abg-diff-utils.cc index bf2a1db3..b8c69261 100644 --- a/src/abg-diff-utils.cc +++ b/src/abg-diff-utils.cc @@ -1,6 +1,6 @@ // -*- Mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -19,8 +19,16 @@ // not, see . #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-diff-utils.h" +ABG_END_EXPORT_DECLARATIONS +// + /// @file /// /// This file defines the declarations found in abg-diff-utils.h diff --git a/src/abg-dwarf-reader.cc b/src/abg-dwarf-reader.cc index 57110ffc..5e8ee0d4 100644 --- a/src/abg-dwarf-reader.cc +++ b/src/abg-dwarf-reader.cc @@ -46,10 +46,18 @@ #include #include #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-dwarf-reader.h" #include "abg-sptr-utils.h" #include "abg-tools-utils.h" +ABG_END_EXPORT_DECLARATIONS +// + using std::string; namespace abigail diff --git a/src/abg-hash.cc b/src/abg-hash.cc index 8a680535..c03cdda9 100644 --- a/src/abg-hash.cc +++ b/src/abg-hash.cc @@ -20,9 +20,16 @@ /// @file +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-hash.h" #include "abg-ir.h" +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-ini.cc b/src/abg-ini.cc index 4573ec10..e1848762 100644 --- a/src/abg-ini.cc +++ b/src/abg-ini.cc @@ -1,6 +1,6 @@ // -*- Mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -31,8 +31,16 @@ #include #include #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-ini.h" +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { namespace ini diff --git a/src/abg-internal.h b/src/abg-internal.h index 521a9f33..6a6ef70a 100644 --- a/src/abg-internal.h +++ b/src/abg-internal.h @@ -39,8 +39,8 @@ ///(function or variable) is going to be global. External ELF files ///will be able to link against the symbol. #define ABG_EXPORTED __attribute__((visibility("default"))) -#define ABG_BEGIN_EXPORT_DECLARATIONS #pagma GCC visibility push(default) -#define ABG_END_EXPORT_DECLARATIONS #pragma GCC visibility pop +#define ABG_BEGIN_EXPORT_DECLARATIONS _Pragma("GCC visibility push(default)") +#define ABG_END_EXPORT_DECLARATIONS _Pragma("GCC visibility pop") #else #define ABG_HIDDEN #define ABG_EXPORTED diff --git a/src/abg-ir.cc b/src/abg-ir.cc index 3b3573ab..a9674c93 100644 --- a/src/abg-ir.cc +++ b/src/abg-ir.cc @@ -33,11 +33,19 @@ #include #include #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-sptr-utils.h" #include "abg-interned-str.h" #include "abg-ir.h" #include "abg-corpus.h" +ABG_END_EXPORT_DECLARATIONS +// + namespace { /// This internal type is a tree walker that walks the sub-tree of a diff --git a/src/abg-libxml-utils.cc b/src/abg-libxml-utils.cc index 64a735d6..9cb30206 100644 --- a/src/abg-libxml-utils.cc +++ b/src/abg-libxml-utils.cc @@ -1,6 +1,6 @@ // -*- mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -22,8 +22,16 @@ #include #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-libxml-utils.h" +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-libzip-utils.cc b/src/abg-libzip-utils.cc index 5d8ad8f6..ba025d5a 100644 --- a/src/abg-libzip-utils.cc +++ b/src/abg-libzip-utils.cc @@ -1,6 +1,6 @@ // -*- mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -20,12 +20,17 @@ /// @file -#include "config.h" +#include "abg-internal.h" #ifdef WITH_ZIP_ARCHIVE +// +ABG_BEGIN_EXPORT_DECLARATIONS -#include #include "abg-libzip-utils.h" +ABG_END_EXPORT_DECLARATIONS +// + +#include namespace abigail { diff --git a/src/abg-reader.cc b/src/abg-reader.cc index 76349c6c..61118d4c 100644 --- a/src/abg-reader.cc +++ b/src/abg-reader.cc @@ -1,6 +1,6 @@ // -*- mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -35,13 +35,22 @@ #include #include #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-libxml-utils.h" +#include "abg-reader.h" #include "abg-corpus.h" #ifdef WITH_ZIP_ARCHIVE #include "abg-libzip-utils.h" #endif +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-suppression.cc b/src/abg-suppression.cc index e5743a43..4e1a7ee6 100644 --- a/src/abg-suppression.cc +++ b/src/abg-suppression.cc @@ -25,12 +25,19 @@ /// This contains the implementation of the suppression engine of /// libabigail. +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-suppression.h" #include "abg-ini.h" #include "abg-sptr-utils.h" #include "abg-comp-filter.h" #include "abg-tools-utils.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + namespace abigail { diff --git a/src/abg-tools-utils.cc b/src/abg-tools-utils.cc index bece9a17..480155b0 100644 --- a/src/abg-tools-utils.cc +++ b/src/abg-tools-utils.cc @@ -33,9 +33,17 @@ #include #include #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include #include "abg-tools-utils.h" +ABG_END_EXPORT_DECLARATIONS +// + using std::string; namespace abigail diff --git a/src/abg-traverse.cc b/src/abg-traverse.cc index 9d5b1184..98e2690a 100644 --- a/src/abg-traverse.cc +++ b/src/abg-traverse.cc @@ -1,6 +1,6 @@ // -*- Mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -20,8 +20,15 @@ /// @file +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-traverse.h" +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-viz-common.cc b/src/abg-viz-common.cc index 531182e5..e7a97536 100644 --- a/src/abg-viz-common.cc +++ b/src/abg-viz-common.cc @@ -18,10 +18,18 @@ // License along with this program; see the file COPYING-LGPLV3. If // not, see . -#include "abg-viz-svg.h" #include #include +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + +#include "abg-viz-svg.h" + +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-viz-dot.cc b/src/abg-viz-dot.cc index ec86710e..03be99f3 100644 --- a/src/abg-viz-dot.cc +++ b/src/abg-viz-dot.cc @@ -1,6 +1,6 @@ // -*- mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -18,10 +18,19 @@ // License along with this program; see the file COPYING-LGPLV3. If // not, see . -#include "abg-viz-dot.h" + #include #include +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + +#include "abg-viz-dot.h" + +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-viz-svg.cc b/src/abg-viz-svg.cc index 79a009db..8cdca6d5 100644 --- a/src/abg-viz-svg.cc +++ b/src/abg-viz-svg.cc @@ -1,6 +1,6 @@ // -*- mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -18,10 +18,18 @@ // License along with this program; see the file COPYING-LGPLV3. If // not, see . -#include "abg-viz-svg.h" #include #include +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + +#include "abg-viz-svg.h" + +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-workers.cc b/src/abg-workers.cc index 0bc32357..49a8ea62 100644 --- a/src/abg-workers.cc +++ b/src/abg-workers.cc @@ -32,7 +32,16 @@ #include #include #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-workers.h" + +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { diff --git a/src/abg-writer.cc b/src/abg-writer.cc index ab6141dd..834938a7 100644 --- a/src/abg-writer.cc +++ b/src/abg-writer.cc @@ -1,6 +1,6 @@ // -*- mode: C++ -*- // -// Copyright (C) 2013-2015 Red Hat, Inc. +// Copyright (C) 2013-2016 Red Hat, Inc. // // This file is part of the GNU Application Binary Interface Generic // Analysis and Instrumentation Library (libabigail). This library is @@ -34,6 +34,11 @@ #include #include #include + +#include "abg-internal.h" +// +ABG_BEGIN_EXPORT_DECLARATIONS + #include "abg-config.h" #include "abg-corpus.h" #include "abg-diff-utils.h" @@ -46,6 +51,9 @@ #include "abg-writer.h" #include "abg-libxml-utils.h" +ABG_END_EXPORT_DECLARATIONS +// + namespace abigail { using std::cerr; diff --git a/tests/Makefile.am b/tests/Makefile.am index becadaa2..33732fa3 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -8,10 +8,12 @@ ZIP_ARCHIVE_TESTS += runtestdot endif endif +AM_CXXFLAGS = $(VISIBILITY_FLAGS) + CXX11_TESTS = if ENABLE_CXX11 CXX11_TESTS += runtestsvg -AM_CXXFLAGS = "-std=gnu++11" +AM_CXXFLAGS += "-std=gnu++11" endif FEDABIPKGDIFF_TEST = diff --git a/tools/Makefile.am b/tools/Makefile.am index 3e53eb11..de35ad47 100644 --- a/tools/Makefile.am +++ b/tools/Makefile.am @@ -49,4 +49,6 @@ abipkgdiffdir = $(bindir) abipkgdiff_LDADD = $(abs_top_builddir)/src/libabigail.la abipkgdiff_LDFLAGS = -pthread -AM_CPPFLAGS=-I$(abs_top_srcdir)/include -I$(abs_top_srcdir)/tools -fPIC +AM_CXXFLAGS = \ +$(VISIBILITY_FLAGS) -I$(abs_top_srcdir)/include \ +-I$(abs_top_srcdir)/tools -fPIC