Build DLL with Cygwin

[source]

[Building and Using DLLs]

> Could you please tell me where I might read more on
> __declspec(dllexport) and __declspec(dllimport)
>
> I do not understand how to use these....

That's a complicated question. Essentially, the MS engineers were on crack
when they designed Windows DLLs. When compiling code to become a DLL, you
must explicitly tell the compiler which symbols(1) will be exported(2) from
the DLL in the declarations(3) of the symbols. When compiling code that
will use a DLL, you must explicitly tell the compiler which symbols will be
imported from DLLs as opposed to statically linked into your program. At
first this doesn't sound so bad, but essentially it means you need three
different versions of all of your declarations for:
1. compiling code to become the DLL
2. compiling code to use the DLL
3. compiling code that will be statically linked

Consider the case of function "foo()" defined in "foo.c" that will be used
in the "main()" of a program "bar.exe" that is defined in "bar.c" . If foo()
is statically linked into bar.exe, your files might look like this:

--- foo.c ---
/* declaration (AKA prototype) of foo(), usually found in .h file */
int foo();

/* definition of foo() */
int foo() { return 1; }
-------------

Compile foo.c:
gcc -c foo.c -o foo.o

--- bar.c ---
/* declaration (AKA prototype) of foo(), usually found in .h file */
int foo();

int main() { return foo(); }
--------------

Compile bar.c and link foo.o into bar.exe statically:

gcc -c bar.c -o bar.o
gcc foo.o bar.o -o bar.exe

However, if foo() should go into a DLL, your files need to look like this:

--- foo.c ---
/* declaration (AKA prototype) of foo(), usually found in .h file */
__declspec(dllexport) int foo(); /* exporting foo() from this DLL */

/* definition of foo() */
int foo() { return 1; }
-------------

Make a DLL from foo.c:

gcc -c foo.c -o foo.o
gcc -Wl,--out-implib,libfoo.import.a -shared -o foo.dll foo.o

This will create the DLL (foo.dll) and the import library for the DLL
(libfoo.import.a).

--- bar.c ---
/* declaration (AKA prototype) of foo(), usually found in .h file */
__declspec(dllimport) int foo(); /* importing foo() from DLL */

int main() { return foo(); }
--------------

Compile and link bar.exe to use foo.dll (via its import library):

gcc -c bar.c -o bar.o
gcc bar.o libfoo.import.a -o bar.exe

bar.exe now uses foo.dll.

So we have three different possible declarations of the function foo():
1. int foo(); /* static linking */
2. __declspec(dllexport) int foo(); /* making DLL with foo() in it */
3. __declspec(dllimport) int foo(); /* importing foo() from DLL */

Which one we use depends on how we are using foo(). The real problem is
that most people don't want to deal with three sets of declarations but want
to just have one header file which is used in all cases. To solve this you
could do something like this:

--- foo.h ---
#if defined(MAKEDLL)
# define INTERFACE __declspec(dllexport)
#elif defined(USEDLL)
# define INTERFACE __declspec(dllimport)
#else
# define INTERFACE
#endif

INTERFACE int foo();
-------------

--- foo.c ---
#include "foo.h"

int foo() { return 1; }
-------------

--- bar.c ---
#include "foo.h"

int main() { return foo(); }
--------------

Now you are only maintaining the declaration of foo() in one place: foo.h.

To compile bar.exe to statically link in foo():

gcc -c foo.c -o foo.o
gcc -c bar.c -o bar.o
gcc foo.o bar.o -o bar.exe

To compile foo() into a DLL:

gcc -DMAKEDLL -c foo.c -o foo.o
gcc -Wl,--out-implib,libfoo.import.a -shared -o foo.dll foo.o

To compile bar.exe to use the DLL:

gcc -DUSEDLL -c bar.c -o bar.exe
gcc bar.o libfoo.import.a -o bar.exe

That's all there is to it.

(1)functions, methods and variables in structs / classes, external
variables
(2)available to programs that use the DLL
(3)function prototypes, class definitions, etc.-- the stuff found in
your header files

Hope this helps,
Carl Thompson

PS: for structs / classes instead of doing this:

class foo {
public:
INTERFACE int bar;
INTERFACE int baz;
}

You can do this:

class INTERFACE foo {
public:
int bar;
int baz;
}

They are both equivalent, but the second way is cleaner.

PPS: I've heard you can do the same thing using separate ".DEF" files,
but I don't know about that.

PPPS: None of this is necessary with reasonable operating systems, such
as Unix or Linux. The compiler and linker automatically export
and import all externally visible symbols when building or using
DLLs (shared libraries). You don't even need a separate import
library.

> ...