gnu/usr.bin/cc34/doc/patches/invoke.texi.patch

   1 $DragonFly: src/gnu/usr.bin/cc34/doc/patches/invoke.texi.patch,v 1.1 2004/12/21 13:10:48 joerg Exp $
   2
   3 Index: invoke.texi
   4 ===================================================================
   5 RCS file: /home/joerg/wd/repository/dragonflybsd/src/contrib/gcc-3.4/gcc/doc/invoke.texi,v
   6 retrieving revision 1.2
   7 diff -u -r1.2 invoke.texi
   8 --- invoke.texi 20 Dec 2004 19:23:25 -0000      1.2
   9 +++ invoke.texi 20 Dec 2004 20:57:46 -0000
  10 @@ -183,7 +183,8 @@
  11  -fno-optional-diags  -fpermissive @gol
  12  -frepo  -fno-rtti  -fstats  -ftemplate-depth-@var{n} @gol
  13  -fuse-cxa-atexit  -fno-weak  -nostdinc++ @gol
  14 --fno-default-inline  -Wabi  -Wctor-dtor-privacy @gol
  15 +-fno-default-inline  -fvisibility-inlines-hidden @gol
  16 +-Wabi  -Wctor-dtor-privacy @gol
  17  -Wnon-virtual-dtor  -Wreorder @gol
  18  -Weffc++  -Wno-deprecated @gol
  19  -Wno-non-template-friend  -Wold-style-cast @gol
  20 @@ -675,7 +676,8 @@
  21  -fargument-alias  -fargument-noalias @gol
  22  -fargument-noalias-global  -fleading-underscore @gol
  23  -ftls-model=@var{model} @gol
  24 --ftrapv  -fwrapv  -fbounds-check}
  25 +-ftrapv  -fwrapv  -fbounds-check @gol
  26 +-fvisibility}
  27  @end table
  28
  29  @menu
  30 @@ -1434,6 +1436,20 @@
  31  destructors, but will only work if your C library supports
  32  @code{__cxa_atexit}.
  33
  34 +@item -fvisibility-inlines-hidden
  35 +@opindex fvisibility-inlines-hidden
  36 +Causes all inlined methods to be marked with
  37 +@code{__attribute__ ((visibility ("hidden")))} so that they do not
  38 +appear in the export table of a DSO and do not require a PLT indirection
  39 +when used within the DSO. Enabling this option can have a dramatic effect
  40 +on load and link times of a DSO as it massively reduces the size of the
  41 +dynamic export table when the library makes heavy use of templates. While
  42 +it can cause bloating through duplication of code within each DSO where
  43 +it is used, often the wastage is less than the considerable space occupied
  44 +by a long symbol name in the export table which is typical when using
  45 +templates and namespaces. For even more savings, combine with the
  46 +@code{-fvisibility=hidden} switch.
  47 +
  48  @item -fno-weak
  49  @opindex fno-weak
  50  Do not use weak symbol support, even if it is provided by the linker.
  51 @@ -11225,6 +11241,54 @@
  52
  53  The default without @option{-fpic} is @code{initial-exec}; with
  54  @option{-fpic} the default is @code{global-dynamic}.
  55 +
  56 +@item -fvisibility=@var{default|internal|hidden|protected}
  57 +@opindex fvisibility
  58 +Set the default ELF image symbol visibility to the specified option - all
  59 +symbols will be marked with this unless overrided within the code.
  60 +Using this feature can very substantially improve linking and
  61 +load times of shared object libraries, produce more optimised
  62 +code, provide near-perfect API export and prevent symbol clashes.
  63 +It is @strong{strongly} recommended that you use this in any shared objects
  64 +you distribute.
  65 +
  66 +Despite the nomenclature, @code{default} always means public ie;
  67 +available to be linked against from outside the shared object.
  68 +@code{protected} and @code{internal} are pretty useless in real-world
  69 +usage so the only other commonly used option will be @code{hidden}.
  70 +The default if -fvisibility isn't specified is @code{default} ie; make every
  71 +symbol public - this causes the same behaviour as previous versions of
  72 +GCC.
  73 +
  74 +A good explanation of the benefits offered by ensuring ELF
  75 +symbols have the correct visibility is given by ``How To Write
  76 +Shared Libraries'' by Ulrich Drepper (which can be found at
  77 +@w{@uref{http://people.redhat.com/~drepper/}}) - however a superior
  78 +solution made possible by this option to marking things hidden when
  79 +the default is public is to make the default hidden and mark things
  80 +public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
  81 +and @code{__attribute__ ((visibility("default")))} instead of
  82 +@code{__declspec(dllexport)} you get almost identical semantics with
  83 +identical syntax. This is a great boon to those working with
  84 +cross-platform projects.
  85 +
  86 +For those adding visibility support to existing code, you may find
  87 +@samp{#pragma GCC visibility} of use. This works by you enclosing
  88 +the declarations you wish to set visibility for with (for example)
  89 +@samp{#pragma GCC visibility push(hidden)} and
  90 +@samp{#pragma GCC visibility pop}. These can be nested up to sixteen
  91 +times. Bear in mind that symbol visibility should be viewed @strong{as
  92 +part of the API interface contract} and thus all new code should
  93 +always specify visibility when it is not the default ie; declarations
  94 +only for use within the local DSO should @strong{always} be marked explicitly
  95 +as hidden as so to avoid PLT indirection overheads - making this
  96 +abundantly clear also aids readability and self-documentation of the code.
  97 +Note that due to ISO C++ specification requirements, operator new and
  98 +operator delete must always be of default visibility.
  99 +
 100 +An overview of these techniques, their benefits and how to use them
 101 +is at @w{@uref{http://www.nedprod.com/programs/gccvisibility.html}}.
 102 +
 103  @end table
 104
 105  @c man end