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.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) \
        !            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;                                                         \
        !           106:  void * IMP(x) = &x;