24/09/2010 Building and Using DLLs

Building and Using DLLs

Prev Chapter 4. Programming with Cygwin Next

Building and Using DLLs

DLLs are Dynamic Link Libraries, which means that they're linked into your program at run time instead of build
time. There are three parts to a DLL:

the exports

the code and data

the import library

The code and data are the parts you write - functions, variables, etc. All these are merged together, like if you
were building one big object files, and put into the dll. They are not put into your .exe at all.

The exports contains a list of functions and variables that the dll makes available to other programs. Think of this
as the list of "global" symbols, the rest being hidden. Normally, you'd create this list by hand with a text editor,
but it's possible to do it automatically from the list of functions in your code. The dlltool program creates the
exports section of the dll from your text file of exported symbols.

The import library is a regular UNIX-like .a library, but it only contains the tiny bit of information needed to tell
the OS how your program interacts with ("imports") the dll. This information is linked into your .exe. This is also
generated by dlltool.

Building DLLs
This page gives only a few simple examples of gcc's DLL-building capabilities. To begin an exploration of the
many additional options, see the gcc documentation and website, currently at http://gcc.gnu.org/

Let's go through a simple example of how to build a dll. For this example, we'll use a single file myprog.c for the
program (myprog.exe) and a single file mydll.c for the contents of the dll (mydll.dll).

Fortunately, with the latest gcc and binutils the process for building a dll is now pretty simple. Say you want to
build this minimal function in mydll.c:

#include <stdio.h>

int
hello()
{
printf ("Hello World!\n");
}

First compile mydll.c to object code:

gcc -c mydll.c
www.cygwin.com/cygwin-ug-net/dll.html 1/3
24/09/2010 Building and Using DLLs

Then, tell gcc that it is building a shared library:

gcc -shared -o mydll.dll mydll.o

That's it! To finish up the example, you can now link to the dll with a simple program:

int
main ()
{
hello ();
}

Then link to your dll with a command like:

gcc -o myprog myprog.c -L./ -lmydll

However, if you are building a dll as an export library, you will probably want to use the complete syntax:

gcc -shared -o cyg${module}.dll \

-Wl,--out-implib=lib${module}.dll.a \
-Wl,--export-all-symbols \
-Wl,--enable-auto-import \
-Wl,--whole-archive ${old_libs} \
-Wl,--no-whole-archive ${dependency_libs}

The name of your library is ${module}, prefixed with cyg for the DLL and lib for the import library. Cygwin
DLLs use the cyg prefix to differentiate them from native-Windows MinGW DLLs, see the MinGW website for
more details. ${old_libs} are all your object files, bundled together in static libs or single object files and the
${dependency_libs} are import libs you need to link against, e.g '-lpng -lz -L/usr/local/special -
lmyspeciallib'.

Linking Against DLLs

If you have an existing DLL already, you need to build a Cygwin-compatible import library. If you have the
source to compile the DLL, see the section called “Building DLLs” for details on having gcc build one for you. If
you do not have the source or a supplied working import library, you can get most of the way by creating a .def
file with these commands (you might need to do this in bash for the quoting to work correctly):

echo EXPORTS > foo.def

nm foo.dll | grep ' T _' | sed 's/.* T _//' >> foo.def

Note that this will only work if the DLL is not stripped. Otherwise you will get an error message: "No symbols in
foo.dll".

Once you have the .def file, you can create an import library from it like this:

dlltool --def foo.def --dllname foo.dll --output-lib foo.a

Prev Up Next
Debugging Cygwin Programs Home Defining Windows Resources
www.cygwin.com/cygwin-ug-net/dll.html 2/3
24/09/2010 Building and Using DLLs

www.cygwin.com/cygwin-ug-net/dll.html 3/3