X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fvisibility.texi;h=0d9b8e3347ee35d82fffef814294405c9ff6ccdf;hb=0443c2f39943017f0aaa0afacbf68fb725858963;hp=23f07566a6ac41c26bf2bc7ccee8f5e2bdf5b17d;hpb=659635d90ba86841af96fed82c1226ae32e9a2cc;p=gnulib.git

diff --git a/doc/visibility.texi b/doc/visibility.texi
index 23f07566a..0d9b8e334 100644
--- a/doc/visibility.texi
+++ b/doc/visibility.texi
@@ -1,7 +1,19 @@
+@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
@@ -32,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
@@ -72,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
@@ -88,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:
@@ -106,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
@@ -134,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)