[Patch/RFA] Fix mingw/cygwin dllimport PR's 7910 (et al) and 11021

[Danny Smith]

> Is there anything in this change which requires documentation tweaks?
>
> cgf

This add documentation for GCC handling of Windows dllimport/dllexport,
including the modifications in the patch submitted here:

http://gcc.gnu.org/ml/gcc-patches/2003-05/msg02391.html

2003-5-31  Danny Smith  <dannysmith@users.sourceforge.net>

	* doc/extend.texi(dllimport): Add documentation.
	(dllexport): Likewise
	(shared): Change Windows NT to just Windows.


*** extend.texi	Sat May 31 09:09:48 2003
--- extend.texi.drs	Sat May 31 10:35:35 2003
*************** use the normal calling convention based 
*** 2563,2568 ****
--- 2563,2673 ----
  This attribute can be used to cancel the effect of the @option{-mlong-calls}
  option.
  
+ @item dllimport
+ @cindex @code{__declspec(dllimport)}
+ On Windows targets, the @code{dllimport} attribute causes the compiler
+ to reference a function or variable via a global pointer to a pointer
+ that is set up by the Windows dll library. The pointer name is formed by
+ combining @code{_imp__} and the function or variable name. The attribute
+ implies @code{extern} storage.
+ 
+ Currently, the attribute is ignored for inlined functions. If the
+ attribute is applied to a symbol @emph{definition}, an error is emitted.
+ If a symbol previousy declared @code{dllimport} is later defined, the
+ attribute is ignored in subsequent references, and a warning is emitted.
+ The attribute is also overriden by a subsequent declaration as
+ @code{dllexport}. 
+ 
+ When applied to C++ classes, the attribute marks static data members,
+ static functions and non-virtual methods as imports. The attribute is
+ ignored for virtual methods to allow vtable lookup using thunks
+ @xref{Vague Linkage}. It is also ignored for inlined member functions
+ and for static constants initialized in-class.
+ 
+ For example, with
+ 
+ @smallexample
+ class __attribute__ ((dllimport)) foo
+ @{
+ public:
+   static int static_var;
+   static const int static_const_var = 1;
+   static void fun ();
+   void method1 () const @{@};
+   void method2 () const;
+   virtual void method3 () const;
+ private:
+   int i_;
+ @};
+ @end smallexample
+ 
+ @code{foo::static_var, foo::fun} and @code{foo::method2} are marked
+ as @code{dllimport}.
+ 
+ On cygwin, mingw and arm-pe targets, @code{__declspec(dllimport)} is
+ recognized as a synonym for @code{__attribute__ ((dllimport))} for
+ compatibility with other Windows compilers.
+ 
+ The use of the @code{dllimport} attribute on functions is not necessary,
+ but provides a small performance benefit by eliminating a thunk in the
+ dll. The use of the @code{dllimport} attribute on imported variables was
+ required on older versions of GNU ld, but can now be avoided by passing
+ the @option{--enable-auto-import} switch to ld. As with functions, using
+ the attribute for a variable eliminates a thunk in the dll. 
+ 
+ One drawback to using this attribute is that a pointer to a function or
+ variable marked as dllimport cannot be used as a constant address. The
+ attribute can be disabled for functions by setting the
+ @option{-mnop-fun-dllimport} flag.
+ 
+ @item dllexport
+ @cindex @code{__declspec(dllexport)}
+ On Windows targets the @code{dllexport} attribute causes the compiler to
+ provide a global pointer to a pointer in a dll, so that it can be
+ referenced with the @code{dllimport} attribute. The pointer name is
+ formed by combining @code{_imp__} and the function or variable name.
+ 
+ Currently, the @code{dllexport}attribute is ignored for inlined
+ functions, but export can be forced by using the
+ @option{-fkeep-inline-function} flag. The attribute is also ignored for
+ for undefined symbols.
+ 
+ When applied to C++ classes. the attribute marks non-inlined functions
+ and static data members as exports. Static consts initialized in-class
+ are not marked unless they are also defined out-of-class.
+ 
+ For example, with
+ 
+ @smallexample
+ class __attribute__ ((dllexport)) foo
+ @{
+   public:
+   static int static_var;
+   static const int const_int = 1;
+   static void static_fun ();
+   void method1 () const @{@};
+   void method2 () const;
+   virtual void method3 () const;
+ private:
+   int i_;
+ @};
+ 
+ int foo::static_var;
+ void foo::static_fun () @{@};
+ void foo::method2 () const @{@};
+ @end smallexample
+ 
+ @code{foo::static_var, foo::fun, foo::method2} and @code{foo::method3}
+ are marked as dllexport.
+ 
+ On cygwin, mingw and arm-pe targets, @code{__declspec(dllexport)} is
+ recognized as a synonym for @code{__attribute__ ((dllexport))} for
+ compatibility with other Windows compilers.
+ 
+ Alternative methods for including the symbol in the dll's export table
+ are to use a .def file with an @code{EXPORTS} section, or with GNU ld,
+ using the @option{--export-all} linker flag.
+ 
  @end table
  
  You can specify multiple attributes in a declaration by separating them
*************** section, consider using the facilities o
*** 3147,3153 ****
  
  @item shared
  @cindex @code{shared} variable attribute
! On Windows NT, in addition to putting variable definitions in a named
  section, the section can also be shared among all running copies of an
  executable or DLL@.  For example, this small program defines shared data
  by putting it in a named section @code{shared} and marking the section
--- 3252,3258 ----
  
  @item shared
  @cindex @code{shared} variable attribute
! On Windows, in addition to putting variable definitions in a named
  section, the section can also be shared among all running copies of an
  executable or DLL@.  For example, this small program defines shared data
  by putting it in a named section @code{shared} and marking the section
*************** You may only use the @code{shared} attri
*** 3170,3176 ****
  attribute with a fully initialized global definition because of the way
  linkers work.  See @code{section} attribute for more information.
  
! The @code{shared} attribute is only available on Windows NT@.
  
  @item tls_model ("@var{tls_model}")
  @cindex @code{tls_model} attribute
--- 3275,3281 ----
  attribute with a fully initialized global definition because of the way
  linkers work.  See @code{section} attribute for more information.
  
! The @code{shared} attribute is only available on Windows@.
  
  @item tls_model ("@var{tls_model}")
  @cindex @code{tls_model} attribute
*************** the @code{int}.
*** 3227,3232 ****
--- 3332,3344 ----
  
  @item weak
  The @code{weak} attribute is described in @xref{Function Attributes}.
+ 
+ @item dllimport
+ The @code{dllimport} attribute is described in @xref{Function Attributes}.
+ 
+ @item dllexport
+ The @code{dllexport} attribute is described in @xref{Function Attributes}.
+ 
  @end table
  
  @subsection M32R/D Variable Attributes

http://mobile.yahoo.com.au - Yahoo! Mobile
- Check & compose your email via SMS on your Telstra or Vodafone mobile.