@itemize @bullet
@item
-It prevents abuse of undocumented APIs of your library. Symbols that
-are not exported from the library cannot be used. This eliminates the
+It prevents abuse of undocumented APIs of your library. Symbols that
+are not exported from the library cannot be used. This eliminates the
problem that when the maintainer of the library changes internals of the
-library, maintainers of other projects cry "breakage". Instead, these
+library, maintainers of other projects cry ``breakage''. Instead, these
maintainers are forced to negotiate the desired API from the maintainer
of the library.
@item
It reduces the risk of symbol collision between your library and other
-libraries. For example, the symbol @samp{readline} is defined in several
+libraries. For example, the symbol @samp{readline} is defined in several
libraries, most of which don't have the same semantics and the same calling
convention as the GNU readline library.
@item
-It reduces the startup time of programs linked to the library. This is
+It reduces the startup time of programs linked to the library. This is
because the dynamic loader has less symbols to process.
@item
-It allows the compiler to generate better code. Within a shared library,
-a call to a function that is a global symbol costs a "call" instruction
+It allows the compiler to generate better code. Within a shared library,
+a call to a function that is a global symbol costs a ``call'' instruction
to a code location in the so-called PLT (procedure linkage table) which
-contains a "jump" instruction to the actual function's code. (This is
+contains a ``jump'' instruction to the actual function's code. (This is
needed so that the function can be overridden, for example by a function
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
+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 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
+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
instruction.
@end itemize
@itemize @bullet
@item
The programmer specifies the list of symbols to be exported when the
-shared library is created. Usually a command-line option is passed
+shared library is created. Usually a command-line option is passed
to the linker, with the name of a file containing the symbols.
The upside of this approach is flexibility: it allows the same code to
-be used in different libraries with different export lists. The downsides
+be used in different libraries with different export lists. The downsides
are: 1. it's a lot of maintenance overhead when the symbol list is platform
dependent, 2. it doesn't work well with C++, due to name mangling.
@item
-The programmer specifies a "hidden" attribute for every variable and
+The programmer specifies a ``hidden'' attribute for every variable and
function that shall not be exported.
The drawbacks of this approach are: Symbols are still exported from
-the library by default. It's a lot of maintenance work to mark every non-
-exported variable and function. But usually the exported API is quite small,
-compared to the internal API of the library. And it's the wrong paradigm:
+the library by default. It's a lot of maintenance work to mark every non-
+exported variable and function. But usually the exported API is quite small,
+compared to the internal API of the library. And it's the wrong paradigm:
It doesn't force thinking when introducing new exported API.
@item
-The programmer specifies a "hidden" attribute for all files that make up
-the shared library, and an "exported" attribute for those symbols in these
+The programmer specifies a ``hidden'' attribute for all files that make up
+the shared library, and an ``exported'' attribute for those symbols in these
files that shall be exported.
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.
+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
+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
+option and the ``visibility'' attribute. (The ``visibility'' attribute
was already supported in GCC 3.4, but without the command line option,
introduced in GCC 4.0, the third approach could not be used.)
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 substituted variable: @@HAVE_VISIBILITY@@. Its value is 1 when symbol
+@samp{-fvisibility=hidden} or nothing. It also defines as a C macro and
+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
Annotate all variable, function and class declarations in all public header
-files of your library with @samp{LIBFOO_DLL_EXPORTED}. This annotation
+files of your library with @samp{LIBFOO_DLL_EXPORTED}. This annotation
can occur at different locations: between the @samp{extern} and the
type or return type, or just before the entity being declared, or after
-the entire declarator. My preference is to put it right after @samp{extern},
+the entire declarator. My preference is to put it right after @samp{extern},
so that the declarations in the header files remain halfway readable.
@end enumerate
Note that the precise control of the exported symbols will not work with
other compilers than GCC >= 4.0, and will not work on systems where the
-assembler or linker lack the support of "hidden" visibility. Therefore,
+assembler or linker lack the support of ``hidden'' visibility. Therefore,
it's good if, in order to reduce the risk of collisions with symbols in
other libraries, you continue to use a prefix specific to your library
for all non-static variables and functions and for all C++ classes in
projects / gnulib.git / commitdiff