Mercurial > hg > octave-nkf > gnulib-hg
annotate doc/lib-symbol-visibility.texi @ 17906:d86e349ad92d
getugroups: Fix Android build
* lib/getugroups.c: Don't reference unsupported {get,set,end}grent
functions.
| author | Kevin Cernekee <cernekee@google.com> |
|---|---|
| date | Wed, 11 Feb 2015 15:22:53 -0800 |
| parents | ab58d4870664 |
| children |
| rev | line source |
|---|---|
| 11442 | 1 @node Exported Symbols of Shared Libraries |
| 2 @section Controlling the Exported Symbols of Shared Libraries | |
| 3 | |
| 4 @c Documentation of gnulib module 'lib-symbol-visibility'. | |
| 5 | |
| 17848 | 6 @c Copyright (C) 2005-2006, 2009-2015 Free Software Foundation, Inc. |
| 11442 | 7 |
| 8 @c Permission is granted to copy, distribute and/or modify this document | |
| 9 @c under the terms of the GNU Free Documentation License, Version 1.3 or | |
| 10 @c any later version published by the Free Software Foundation; with no | |
| 11 @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover | |
| 12 @c Texts. A copy of the license is included in the ``GNU Free | |
| 13 @c Documentation License'' file as part of this distribution. | |
| 14 | |
| 15 The @code{lib-symbol-visibility} module allows precise control of the | |
| 16 symbols exported by a shared library. This is useful because | |
| 17 | |
| 18 @itemize @bullet | |
| 19 @item | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
20 It prevents abuse of undocumented APIs of your library. Symbols that |
|
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
21 are not exported from the library cannot be used. This eliminates the |
| 11442 | 22 problem that when the maintainer of the library changes internals of the |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
23 library, maintainers of other projects cry ``breakage''. Instead, these |
| 11442 | 24 maintainers are forced to negotiate the desired API from the maintainer |
| 25 of the library. | |
| 26 | |
| 27 @item | |
| 28 It reduces the risk of symbol collision between your library and other | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
29 libraries. For example, the symbol @samp{readline} is defined in several |
| 11442 | 30 libraries, most of which don't have the same semantics and the same calling |
| 31 convention as the GNU readline library. | |
| 32 | |
| 33 @item | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
34 It reduces the startup time of programs linked to the library. This is |
| 11442 | 35 because the dynamic loader has less symbols to process. |
| 36 | |
| 37 @item | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
38 It allows the compiler to generate better code. Within a shared library, |
|
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
39 a call to a function that is a global symbol costs a ``call'' instruction |
| 11442 | 40 to a code location in the so-called PLT (procedure linkage table) which |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
41 contains a ``jump'' instruction to the actual function's code. (This is |
| 11442 | 42 needed so that the function can be overridden, for example by a function |
| 43 with the same name in the executable or in a shared library interposed | |
| 44 with @code{LD_PRELOAD}.) Whereas a call to a function for which the compiler | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
45 can assume that it is in the same shared library is just a direct ``call'' |
|
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
46 instructions. Similarly for variables: A reference to a global variable |
| 11442 | 47 fetches a pointer in the so-called GOT (global offset table); this is a |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
48 pointer to the variable's memory. So the code to access it is two memory |
|
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
49 load instructions. Whereas for a variable which is known to reside in the |
| 11442 | 50 same shared library, it is just a direct memory access: one memory load |
| 51 instruction. | |
| 52 @end itemize | |
| 53 | |
| 54 There are traditionally three ways to specify the exported symbols of a | |
| 55 shared library. | |
| 56 | |
| 57 @itemize @bullet | |
| 58 @item | |
| 59 The programmer specifies the list of symbols to be exported when the | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
60 shared library is created. Usually a command-line option is passed |
| 11442 | 61 to the linker, with the name of a file containing the symbols. |
| 62 | |
| 63 The upside of this approach is flexibility: it allows the same code to | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
64 be used in different libraries with different export lists. The downsides |
| 11442 | 65 are: 1. it's a lot of maintenance overhead when the symbol list is platform |
| 66 dependent, 2. it doesn't work well with C++, due to name mangling. | |
| 67 | |
| 68 @item | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
69 The programmer specifies a ``hidden'' attribute for every variable and |
| 11442 | 70 function that shall not be exported. |
| 71 | |
| 72 The drawbacks of this approach are: Symbols are still exported from | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
73 the library by default. It's a lot of maintenance work to mark every non- |
|
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
74 exported variable and function. But usually the exported API is quite small, |
|
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
75 compared to the internal API of the library. And it's the wrong paradigm: |
| 11442 | 76 It doesn't force thinking when introducing new exported API. |
| 77 | |
| 78 @item | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
79 The programmer specifies a ``hidden'' attribute for all files that make up |
|
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
80 the shared library, and an ``exported'' attribute for those symbols in these |
| 11442 | 81 files that shall be exported. |
| 82 | |
| 83 This is perfect: It burdens the maintainer only for exported API, not | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
84 for library-internal API. And it keeps the annotations in the source code. |
| 11442 | 85 @end itemize |
| 86 | |
| 87 GNU libtool's @option{-export-symbols} option implements the first approach. | |
| 88 | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
89 This gnulib module implements the third approach. For this it relies on |
| 11442 | 90 GNU GCC 4.0 or newer, namely on its @samp{-fvisibility=hidden} command-line |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
91 option and the ``visibility'' attribute. (The ``visibility'' attribute |
| 11442 | 92 was already supported in GCC 3.4, but without the command line option, |
| 93 introduced in GCC 4.0, the third approach could not be used.) | |
| 94 | |
| 95 More explanations on this subject can be found in | |
| 17223 | 96 @url{http://gcc.gnu.org/wiki/Visibility}, which contains more details |
| 97 on the GCC features and additional advice for C++ libraries, and in | |
| 98 Ulrich Drepper's paper @url{http://people.redhat.com/drepper/dsohowto.pdf}, | |
| 99 which also explains other tricks for reducing the startup time impact | |
| 11442 | 100 of shared libraries. |
| 101 | |
| 102 The gnulib autoconf macro @code{gl_VISIBILITY} tests for GCC 4.0 or newer. | |
| 103 It defines a Makefile variable @code{@@CFLAG_VISIBILITY@@} containing | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
104 @samp{-fvisibility=hidden} or nothing. It also defines as a C macro and |
|
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
105 as a substituted variable: @@HAVE_VISIBILITY@@. Its value is 1 when symbol |
| 11442 | 106 visibility control is supported, and 0 otherwise. |
| 107 | |
| 108 To use this module in a library, say libfoo, you will do these steps: | |
| 109 | |
| 110 @enumerate | |
| 111 @item | |
| 112 Add @code{@@CFLAG_VISIBILITY@@} or (in a Makefile.am) | |
| 113 @code{$(CFLAG_VISIBILITY)} to the CFLAGS for the compilation of the sources | |
| 114 that make up the library. | |
| 115 | |
| 116 @item | |
| 117 Add a C macro definition, say @samp{-DBUILDING_LIBFOO}, to the CPPFLAGS | |
| 118 for the compilation of the sources that make up the library. | |
| 119 | |
| 120 @item | |
| 121 Define a macro specific to your library like this. | |
| 122 @smallexample | |
| 123 #if BUILDING_LIBFOO && HAVE_VISIBILITY | |
| 124 #define LIBFOO_DLL_EXPORTED __attribute__((__visibility__("default"))) | |
| 125 #else | |
| 126 #define LIBFOO_DLL_EXPORTED | |
| 127 #endif | |
| 128 @end smallexample | |
| 129 This macro should be enabled in all public header files of your library. | |
| 130 | |
| 131 @item | |
| 132 Annotate all variable, function and class declarations in all public header | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
133 files of your library with @samp{LIBFOO_DLL_EXPORTED}. This annotation |
| 11442 | 134 can occur at different locations: between the @samp{extern} and the |
| 135 type or return type, or just before the entity being declared, or after | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
136 the entire declarator. My preference is to put it right after @samp{extern}, |
| 11442 | 137 so that the declarations in the header files remain halfway readable. |
| 138 @end enumerate | |
| 139 | |
| 140 Note that the precise control of the exported symbols will not work with | |
| 141 other compilers than GCC >= 4.0, and will not work on systems where the | |
|
11443
1319abc494f3
Follow texinfo style conventions.
Bruno Haible <bruno@clisp.org>
parents:
11442
diff
changeset
|
142 assembler or linker lack the support of ``hidden'' visibility. Therefore, |
| 11442 | 143 it's good if, in order to reduce the risk of collisions with symbols in |
| 144 other libraries, you continue to use a prefix specific to your library | |
| 145 for all non-static variables and functions and for all C++ classes in | |
| 146 your library. | |
| 147 | |
| 148 Note about other compilers: MSVC support can be added easily, by extending | |
| 149 the definition of the macro mentioned above, to something like this: | |
| 150 @smallexample | |
| 151 #if BUILDING_LIBFOO && HAVE_VISIBILITY | |
| 152 #define LIBFOO_DLL_EXPORTED __attribute__((__visibility__("default"))) | |
| 153 #elif BUILDING_LIBFOO && defined _MSC_VER | |
| 154 #define LIBFOO_DLL_EXPORTED __declspec(dllexport) | |
| 155 #elif defined _MSC_VER | |
| 156 #define LIBFOO_DLL_EXPORTED __declspec(dllimport) | |
| 157 #else | |
| 158 #define LIBFOO_DLL_EXPORTED | |
| 159 #endif | |
| 160 @end smallexample |