Return to export.h CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libiconv / woe32dll

Annotation of embedaddon/libiconv/woe32dll/export.h, revision 1.1.1.2

1.1       misho       1: /* Exporting symbols from Cygwin shared libraries.
                      2:    Copyright (C) 2006 Free Software Foundation, Inc.
                      3:    Written by Bruno Haible <bruno@clisp.org>, 2006.
                      4: 
                      5:    This program is free software: you can redistribute it and/or modify
                      6:    it under the terms of the GNU General Public License as published by
                      7:    the Free Software Foundation; either version 3 of the License, or
                      8:    (at your option) any later version.
                      9: 
                     10:    This program is distributed in the hope that it will be useful,
                     11:    but WITHOUT ANY WARRANTY; without even the implied warranty of
                     12:    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
                     13:    GNU General Public License for more details.
                     14: 
                     15:    You should have received a copy of the GNU General Public License
                     16:    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
                     17: 
                     18: /* There are four ways to build shared libraries on Cygwin:
                     19: 
                     20:    - Export only functions, no variables.
                     21:      This has the drawback of severely affecting the programming style in use.
                     22:      It does not let the programmer use full ANSI C.  It lets one platform
                     23:      dictate the code style on all platforms.  This is unacceptable.
                     24: 
                     25:    - Use the GNU ld --enable-auto-import option.  It is the default on Cygwin
                     26:      since July 2005. But it has three fatal drawbacks:
                     27:        - It produces executables and shared libraries with relocations in the
                     28:          .text segment, defeating the principles of virtual memory.
                     29:        - For some constructs such as
                     30:              extern int var;
                     31:              int * const b = &var;
                     32:          it creates an executable that will give an error at runtime, rather
                     33:          than either a compile-time or link-time error or a working executable.
                     34:          (This is with both gcc and g++.) Whereas this code, not relying on
                     35:          auto-import:
                     36:              extern __declspec (dllimport) int var;
                     37:              int * const b = &var;
                     38:          gives a compile-time error with gcc and works with g++.
                     39:        - It doesn't work in some cases (references to a member field of an
                     40:          exported struct variable, or to a particular element of an exported
                     41:          array variable), requiring code modifications.  Again one platform
                     42:          dictates code modifications on all platforms.
                     43: 
                     44:      This is unacceptable.  Therefore we disable this option, through the
                     45:      woe32-dll.m4 autoconf macro.
                     46: 
                     47:    - Define a macro that expands to  __declspec(dllexport)  when building
                     48:      the library and to  __declspec(dllimport)  when building code outside
                     49:      the library, and use it in all header files of the library.
                     50:      This is acceptable if
                     51:        1. the header files are unique to this library (not shared with
                     52:           other packages), and
                     53:        2. the library sources are contained in one directory, making it easy
                     54:           to define a -DBUILDING_LIBXYZ flag for the library.
                     55:      Example:
                     56:          #ifdef BUILDING_LIBASPRINTF
                     57:          #define LIBASPRINTF_DLL_EXPORTED __declspec(dllexport)
                     58:          #else
                     59:          #define LIBASPRINTF_DLL_EXPORTED __declspec(dllimport)
                     60:          #endif
                     61: 
                     62:      We use this technique for the libintl and the libasprintf libraries.
                     63: 
                     64:    - Define a macro that expands to  __declspec(dllimport)  always, and use
                     65:      it in all header files of the library.  Use an explicit export list for
                     66:      the library.
                     67:      This is acceptable if
                     68:        1. the programming language is not C++ (because the name mangling of
                     69:           static struct/class fields and of variables in namespaces makes it
                     70:           hard to maintain an export list).
                     71:      The benefit of this approach is that the partitioning of the source files
                     72:      into libraries (which source file goes into which library) does not
                     73:      affect the source code; only the Makefiles reflect it.
                     74:      The performance loss due to the unnecessary indirection for references
                     75:      to variables from within the library defining the variable is acceptable.
                     76: 
                     77:      We use this technique for libgettextlib (because it contains many gnulib
                     78:      modules) and for libgettextsrc (because this makes it easy to move source
                     79:      code from an msg* program to libgettextsrc).  The macro is called
                     80:      DLL_VARIABLE.
                     81: 
                     82:    This file allows building an explicit export list.  You can either
                     83:      - specify the variables to be exported, and use the GNU ld option
                     84:        --export-all-symbols to export all function names, or
                     85:      - specify the variables and functions to be exported explicitly.
                     86: 
                     87:    Note: --export-all-symbols is the default when no other symbol is explicitly
                     88:    exported.  This means, the use of an explicit export on the variables has
                     89:    the effect of no longer exporting the functions! - until the option
                     90:    --export-all-symbols is used.  */
                     91: 
                     92:  /* IMP(x) is a symbol that contains the address of x.  */
                     93: #define IMP(x) _imp__##x
                     94: 
                     95:  /* Ensure that the variable x is exported from the library, and that a
                     96:     pseudo-variable IMP(x) is available.  */
                     97: #define VARIABLE(x) \
1.1.1.2 ! misho      98:  /* Export x without redefining x.  This code was found by compiling a  \
        !            99:     snippet:                                                            \
        !           100:       extern __declspec(dllexport) int x; int x = 42;  */               \
        !           101:  asm (".section .drectve\n");                                           \
        !           102:  asm (".ascii \" -export:" #x ",data\"\n");                             \
        !           103:  asm (".data\n");                                                       \
        !           104:  /* Allocate a pseudo-variable IMP(x).  */                              \
        !           105:  extern int x;                                                          \
1.1       misho     106:  void * IMP(x) = &x;