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