Panda3D
dtoolsymbols.h
1 /* Filename: dtoolsymbols.h
2  * Created by: drose (18Feb00)
3  *
4  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
5  *
6  * PANDA 3D SOFTWARE
7  * Copyright (c) Carnegie Mellon University. All rights reserved.
8  *
9  * All use of this software is subject to the terms of the revised BSD
10  * license. You should have received a copy of this license along
11  * with this source code in a file named "LICENSE."
12  *
13  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
14 
15 #ifndef DTOOLSYMBOLS_H
16 #define DTOOLSYMBOLS_H
17 
18 
19 /*
20  This file defines a slew of symbols that have particular meaning
21  only when compiling in the WIN32 environment. These symbols are
22  prefixed to each class declaration, and each global function, that
23  is to be made visible outside of a DLL.
24 
25  The problem is that in Windows, you must prefix each DLL-public
26  symbol with "__declspec(dllexport)" when you are compiling the DLL,
27  but with "__declspec(dllimport)" when you are compiling code that
28  links with the DLL. This strange convention means that you must, in
29  principle, have two different .h files for a DLL: one to use for
30  compiling the DLL (it must export all of the symbols), and a
31  different one for presenting the public interface for other users to
32  use (it must import all of the same symbols).
33 
34  In practice, of course, maintaining two different .h files is silly
35  and error-prone; almost everyone solves this problem by defining a
36  macro that evaluates to "__declspec(dllexport)" in one case and
37  "__declspec(dllimport)" in another case. Many systems use the
38  system macro _DLL to switch between these two case, which works well
39  in a simple system because _DLL is defined only if compiler is
40  currently generating code for a DLL. So you can export the symbols
41  if _DLL is defined, and import them if it is not defined.
42 
43  However, this fails if you are compiling a DLL that wants to import
44  symbols from another DLL, since in this case _DLL is defined, but
45  the symbols in the other DLL need to be imported, not exported.
46 
47  In the general case of compiling multiple DLL's that might reference
48  each other's symbols, we need have a separate macro for each DLL.
49  Then when we are compiling code for each DLL, the macro for that
50  particular DLL evaluates to "__declspec(dllexport)", exporting all
51  the symbols from the DLL, while all the other DLL's macros evaluate
52  to "__declspec(dllimport)", importing all the symbols from the other
53  DLL's.
54 
55  That is the approach we have taken here in Panda. When we are
56  compiling code for a particular DLL, the build scripts define the
57  macro BUILDING_libname on the command line. This file then uses
58  that macro to define EXPCL_libname appropriately for each DLL; this
59  macro is then used to prefix each symbol to be exported from the
60  DLL. The macro name stands for "export class", since it is used
61  most often to mark a class for export, although the same macro can
62  be used to export global functions. (We also define EXPTP_libname,
63  which is used in conjunction with exporting template instantiations,
64  another dicey task in Windows. It is used far less often.)
65 
66  Of course, this whole thing only matters under WIN32. In the rest
67  of the world we don't have to deal with this nonsense, and so we
68  can define all of these stupid symbols to the empty string.
69  */
70 
71 #define EXPCL_EMPTY
72 
73 #ifdef BUILDING_DTOOL
74  #define EXPCL_DTOOL EXPORT_CLASS
75  #define EXPTP_DTOOL EXPORT_TEMPL
76 #else
77  #define EXPCL_DTOOL IMPORT_CLASS
78  #define EXPTP_DTOOL IMPORT_TEMPL
79 #endif
80 
81 #ifdef BUILDING_DTOOLCONFIG
82  #define EXPCL_DTOOLCONFIG EXPORT_CLASS
83  #define EXPTP_DTOOLCONFIG EXPORT_TEMPL
84 #else
85  #define EXPCL_DTOOLCONFIG IMPORT_CLASS
86  #define EXPTP_DTOOLCONFIG IMPORT_TEMPL
87 #endif
88 
89 #ifdef BUILDING_MISC
90  #define EXPCL_MISC EXPORT_CLASS
91  #define EXPTP_MISC EXPORT_TEMPL
92 #else /* BUILDING_MISC */
93  #define EXPCL_MISC IMPORT_CLASS
94  #define EXPTP_MISC IMPORT_TEMPL
95 #endif /* BUILDING_MISC */
96 
97 /* These two are always defined empty, because pystub is statically
98  built. But we leave the symbol around in case we change our minds
99  to make pystub once again be a dynamic library. */
100 #define EXPCL_PYSTUB
101 #define EXPTP_PYSTUB
102 
103 #endif