filevercmp: Move hidden files up in ordering.

[gnulib.git] / doc / visibility.texi

diff --git a/doc/visibility.texi b/doc/visibility.texi
index 07e8836..0d9b8e3 100644 (file)
--- a/doc/visibility.texi
+++ b/doc/visibility.texi
@@ -1,16 +1,19 @@
+@node Exported Symbols of Shared Libraries
+@section Controlling the Exported Symbols of Shared Libraries
+
 @c Documentation of gnulib module 'visibility'.
 
-@c Copyright (C) 2005 Free Software Foundation, Inc.
+@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.2 or
+@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.
 
-This module allows precise control of the symbols exported by a shared
-library.  This is useful because
+The @code{visibility} module allows precise control of the symbols
+exported by a shared library.  This is useful because
 
 @itemize @bullet
 @item
@@ -41,7 +44,7 @@ with the same name in the executable or in a shared library interposed
 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
@@ -81,6 +84,8 @@ This is perfect: It burdens the maintainer only for exported API, not
 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
@@ -97,7 +102,7 @@ of shared libraries.
 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:
@@ -115,7 +120,7 @@ for the compilation of the sources that make up the library.
 @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
@@ -143,9 +148,9 @@ your library.
 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)