From: Bruno Haible Date: Wed, 1 Apr 2009 22:31:54 +0000 (+0200) Subject: Follow texinfo style conventions. X-Git-Tag: v0.1~6044 X-Git-Url: http://erislabs.net/gitweb/?a=commitdiff_plain;h=3bf152e06b7fccd21d3cb957d8fffb563526b3b6;p=gnulib.git Follow texinfo style conventions. --- diff --git a/ChangeLog b/ChangeLog index 8e5feedb4..1de821ef6 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ 2009-04-01 Bruno Haible + * doc/lib-symbol-visibility.texi: Follow texinfo style conventions. + +2009-04-01 Bruno Haible + Rename module 'visibility'. * modules/lib-symbol-visibility: Renamed from modules/visibility. * doc/lib-symbol-visibility.texi: Renamed from visibility.texi. diff --git a/doc/lib-symbol-visibility.texi b/doc/lib-symbol-visibility.texi index fbd8d1e10..14b0e8c9c 100644 --- a/doc/lib-symbol-visibility.texi +++ b/doc/lib-symbol-visibility.texi @@ -17,36 +17,36 @@ symbols exported by a shared library. This is useful because @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 @@ -57,38 +57,38 @@ shared library. @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.) @@ -101,8 +101,8 @@ 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 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: @@ -130,16 +130,16 @@ This macro should be enabled in all public header files of your library. @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