diff options
author | Geoffrey Keating <geoffk@apple.com> | 2006-04-05 18:34:37 +0000 |
---|---|---|
committer | Geoffrey Keating <geoffk@apple.com> | 2006-04-05 18:34:37 +0000 |
commit | 241319a6c5b28623ee3f321ce74b6b1b03023872 (patch) | |
tree | e5c87ac2d8143ed03d05ca80a3a9d6fedd8b0091 | |
parent | 0a5a3014f84f05782cc2168015c7a6fa84fc9280 (diff) |
Radar 4383613
* doc/extend.texi (Function Attributes): Rewrite visibility
attribute documentation.
* doc/invoke.texi (C++ Dialect Options): Rewrite
-fvisibility-inlines-hidden documentation to describe something
entirely different, although in practise compatible.
(Code Gen Options): Warn about system headers in -fvisibility=
documentation.
git-svn-id: https://gcc.gnu.org/svn/gcc/branches/apple-local-200502-branch@112713 138bc75d-0d04-0410-961f-82ee72b054a4
-rw-r--r-- | gcc/ChangeLog | 11 | ||||
-rw-r--r-- | gcc/doc/extend.texi | 82 | ||||
-rw-r--r-- | gcc/doc/invoke.texi | 37 |
3 files changed, 100 insertions, 30 deletions
diff --git a/gcc/ChangeLog b/gcc/ChangeLog index b1c32cedae1..d321ec2bfb0 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,14 @@ +2006-04-04 Geoffrey Keating <geoffk@apple.com> + + Radar 4383613 + * doc/extend.texi (Function Attributes): Rewrite visibility + attribute documentation. + * doc/invoke.texi (C++ Dialect Options): Rewrite + -fvisibility-inlines-hidden documentation to describe something + entirely different, although in practise compatible. + (Code Gen Options): Warn about system headers in -fvisibility= + documentation. + 2006-03-22 Eric Christopher <echristo@apple.com> Radar 4419200 diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index c655b8fb9d2..54f2e2c633b 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -2340,8 +2340,10 @@ inline assembly. @item visibility ("@var{visibility_type}") @cindex @code{visibility} attribute -The @code{visibility} attribute on ELF targets causes the declaration -to be emitted with default, hidden, protected or internal visibility. +@c APPLE LOCAL begin mainline 2006-04-03 4383613 +This attribute affects the linkage of the declaration to which it is attached. +There are four supported @var{visibility_type} values: default, +hidden, protected or internal visibility. @smallexample void __attribute__ ((visibility ("protected"))) @@ -2349,41 +2351,77 @@ f () @{ /* @r{Do something.} */; @} int i __attribute__ ((visibility ("hidden"))); @end smallexample -See the ELF gABI for complete details, but the short story is: +The possible values of @var{visibility_type} correspond to the +visibility settings in the ELF gABI. @table @dfn @c keep this list of visibilities in alphabetical order. @item default -Default visibility is the normal case for ELF@. This value is -available for the visibility attribute to override other options -that may change the assumed visibility of symbols. +Default visibility is the normal case for the object file format. +This value is available for the visibility attribute to override other +options that may change the assumed visibility of entities. + +On ELF, default visibility means that the declaration is visible to other +modules and, in shared libraries, means that the declared entity may be +overridden. + +On Darwin, default visibility means that the declaration is visible to +other modules. + +Default visibility corresponds to ``external linkage'' in the language. @item hidden -Hidden visibility indicates that the symbol will not be placed into -the dynamic symbol table, so no other @dfn{module} (executable or -shared library) can reference it directly. +Hidden visibility indicates that the entity declared will have a new +form of linkage, which we'll call ``hidden linkage''. Two +declarations of an object with hidden linkage refer to the same object +if they are in the same shared object. @item internal Internal visibility is like hidden visibility, but with additional -processor specific semantics. Unless otherwise specified by the psABI, -GCC defines internal visibility to mean that the function is @emph{never} -called from another module. Note that hidden symbols, while they cannot -be referenced directly by other modules, can be referenced indirectly via -function pointers. By indicating that a symbol cannot be called from -outside the module, GCC may for instance omit the load of a PIC register -since it is known that the calling function loaded the correct value. +processor specific semantics. Unless otherwise specified by the +psABI, GCC defines internal visibility to mean that a function is +@emph{never} called from another module. Compare this with hidden +functions which, while they cannot be referenced directly by other +modules, can be referenced indirectly via function pointers. By +indicating that a function cannot be called from outside the module, +GCC may for instance omit the load of a PIC register since it is known +that the calling function loaded the correct value. @item protected -Protected visibility indicates that the symbol will be placed in the -dynamic symbol table, but that references within the defining module -will bind to the local symbol. That is, the symbol cannot be overridden -by another module. +Protected visibility is like default visibility except that it +indicates that references within the defining module will bind to the +definition in that module. That is, the declared entity cannot be +overridden by another module. @end table -Not all ELF targets support this attribute. - +All visibilities are supported on many, but not all, ELF targets +(supported when the assembler supports the @samp{.visibility} +pseudo-op). Default visibility is supported everywhere. Hidden +visibility is supported on Darwin targets. + +The visibility attribute should be applied only to declarations which +would otherwise have external linkage. The attribute should be applied +consistently, so that the same entity should not be declared with +different settings of the attribute. + +In C++, the visibility attribute applies to types as well as functions +and objects, because in C++ types have linkage. There are some bugs +in the C++ support for this flag, for example a template which has a +hidden type as a parameter is not properly hidden. +@c bugzilla 26612 + +In C++, you can mark member functions and static member variables of a +class with the visibility attribute. This is useful if if you know a +particular method or static member variable should only be used from +one shared object; then you can mark it hidden while the rest of the +class has default visibility. Care must be taken to avoid breaking +the One Definition Rule; for example, it is not useful to mark a +method which is defined inside a class definition as hidden without +marking the whole class as hidden. + +@c APPLE LOCAL end mainline 2006-04-03 4383613 @item warn_unused_result @cindex @code{warn_unused_result} attribute The @code{warn_unused_result} attribute causes a warning to be emitted diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index cff62f0f0c6..1233854920e 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -1762,18 +1762,30 @@ if the runtime routine is not available. @item -fvisibility-inlines-hidden @opindex fvisibility-inlines-hidden -Causes all inlined methods to be marked with +@c APPLE LOCAL begin mainline 2006-04-03 4383613 +This switch declares that the user does not attempt to compare +pointers to inline methods where the addresses of the two functions +were taken in different shared objects. + +The effect of this is that GCC may, effectively, mark inline methods with @code{__attribute__ ((visibility ("hidden")))} so that they do not appear in the export table of a DSO and do not require a PLT indirection when used within the DSO@. Enabling this option can have a dramatic effect on load and link times of a DSO as it massively reduces the size of the -dynamic export table when the library makes heavy use of templates. While -it can cause bloating through duplication of code within each DSO where -it is used, often the wastage is less than the considerable space occupied -by a long symbol name in the export table which is typical when using -templates and namespaces. For even more savings, combine with the -@option{-fvisibility=hidden} switch. +dynamic export table when the library makes heavy use of templates. + +The behaviour of this switch is not quite the same as marking the +methods as hidden directly. Normally if there is a class with default +visibility which has a hidden method, the effect of this is that the +method must be defined in only one shared object. This switch does +not have this restriction. +You may mark a method as having a visibility explicitly to negate the +effect of the switch for that method. For example, if you do want to +compare pointers to a particular inline method, you might mark it as +having default visibility. + +@c APPLE LOCAL end mainline 2006-04-03 4383613 @c APPLE LOCAL begin ms tinfo compat 4230099 @item -fvisibility-ms-compat @opindex fvisibility-ms-compat @@ -1782,7 +1794,8 @@ linkage model compatible with that of Microsoft Visual Studio. The flag makes these changes to GCC's linkage model: -1. It sets the default visibility to 'hidden', like @option{-fvisibility=hidden}. +1. It sets the default visibility to 'hidden', like +@option{-fvisibility=hidden}. 2. Types, but not their members, are not hidden by default. 3. The One Definition Rule is relaxed for types without explicit visibility specifications which are defined in more than one different @@ -13284,6 +13297,14 @@ abundantly clear also aids readability and self-documentation of the code. Note that due to ISO C++ specification requirements, operator new and operator delete must always be of default visibility. +@c APPLE LOCAL begin mainline 2006-04-03 4383613 +Be aware that headers from outside your project, in particular system +headers and headers from any other library you use, may not be +expecting to be compiled with visibility other than the default. You +may need to explicitly say @samp{#pragma GCC visibility push(default)} +before including any such headers. +@c APPLE LOCAL end mainline 2006-04-03 4383613 + An overview of these techniques, their benefits and how to use them is at @w{@uref{http://www.nedprod.com/programs/gccvisibility.html}}. |