+@node Exported Symbols of Shared Libraries
+@section Controlling the Exported Symbols of Shared Libraries
+
@c Documentation of gnulib module 'visibility'.
-This module allows precise control of the symbols exported by a shared
-library. This is useful because
+@c Copyright (C) 2005-2006, 2009 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+@c Texts. A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
+The @code{visibility} module allows precise control of the symbols
+exported by a shared library. This is useful because
@itemize @bullet
@item
with @code{LD_PRELOAD}.) Whereas a call to a function for which the compiler
can assume that it is in the same shared library is just a direct "call"
instructions. Similarly for variables: A reference to a global variable
-fetches a pointer in the so-called GOT (global offset table); this pointer
+fetches a pointer in the so-called GOT (global offset table); this is a
pointer to the variable's memory. So the code to access it is two memory
load instructions. Whereas for a variable which is known to reside in the
same shared library, it is just a direct memory access: one memory load
for library-internal API. And it keeps the annotations in the source code.
@end itemize
+GNU libtool's @option{-export-symbols} option implements the first approach.
+
This gnulib module implements the third approach. For this it relies on
GNU GCC 4.0 or newer, namely on its @samp{-fvisibility=hidden} command-line
option and the "visibility" attribute. (The "visibility" attribute
The gnulib autoconf macro @code{gl_VISIBILITY} tests for GCC 4.0 or newer.
It defines a Makefile variable @code{@@CFLAG_VISIBILITY@@} containing
@samp{-fvisibility=hidden} or nothing. It also defines as a C macro and
-as a Makefile variable: @@HAVE_VISIBILITY@@. Its value is 1 when symbol
+as a substituted variable: @@HAVE_VISIBILITY@@. Its value is 1 when symbol
visibility control is supported, and 0 otherwise.
To use this module in a library, say libfoo, you will do these steps:
@item
Define a macro specific to your library like this.
@smallexample
-#if @@HAVE_VISIBILITY@@ && BUILDING_LIBFOO
+#if BUILDING_LIBFOO && HAVE_VISIBILITY
#define LIBFOO_DLL_EXPORTED __attribute__((__visibility__("default")))
#else
#define LIBFOO_DLL_EXPORTED
Note about other compilers: MSVC support can be added easily, by extending
the definition of the macro mentioned above, to something like this:
@smallexample
-#if @@HAVE_VISIBILITY@@ && BUILDING_LIBFOO
+#if BUILDING_LIBFOO && HAVE_VISIBILITY
#define LIBFOO_DLL_EXPORTED __attribute__((__visibility__("default")))
-#elif defined _MSC_VER && BUILDING_LIBFOO
+#elif BUILDING_LIBFOO && defined _MSC_VER
#define LIBFOO_DLL_EXPORTED __declspec(dllexport)
#elif defined _MSC_VER
#define LIBFOO_DLL_EXPORTED __declspec(dllimport)