Shared libraries with Eclipse CDT and cygwin on Windows

“Can you help me use shared libraries with Eclipse CDT, managed make and cygwin?“, I was asked yesterday. Read on for a list of common pitfalls and detailed instructions.

The instructions are based on the latest CDT release (Galileo) and cygwin (make 3.81, gcc 3.4.4). They are applicable to CDT’s managed make projects (that means CDT generates a makefile to build project).

The Pitfalls

It turns out that using a shared library on Windows is not as straight forward as you think. There are several pitfalls waiting for the unaware to fall into:

1. Recent versions of cygwin’s make insist on cygwin-style paths instead of windows paths (/cygdrive/c/foo instead of c:\foo). CDT is not picky about this and will generate an incorrect makefile, if you use workspace relative paths:

make all
example.d:1: *** multiple target patterns.  Stop.

The solution is to use absolute cygwin paths, such as: /cygdrive/c/workspace/mymath

2. The compiler and linker will not find the header files / library unless you set the appropriate parameters. The compiler needs an include path (-I). The linker needs the library name (-l) and library search path (-L). These settings are scattered in two places in the project properties. Their location is not obvious for a first-time user (details below).

3. When launching, Windows will not find the shared library (.dll) and greet you with the error pictured below. Unix users might try to set the LD_LIBRARY_PATH, which has no effect on Windows. The solution is to append the directory containing the .dll to the PATH (MSDN Article). Restart Eclipse for the changed PATH to take effect.

The remainder of the post walks you through the process of creating and using a simple shared library with cygwin and CDT.

Creating a Shared Library with CDT

Follow these instructions to create a shared library project with CDT.

1. File > New > Project > C Project > Next. Project name: mymath. Ensure “use default location” is checked. Note the location: c:\workspace\mymath — we’ll need it later. Project type: Shared Library; Empty Project. Hit Finish.

2. Create a header file (mymath.h) and the corresponding implementation (mymath.c). The example below provides a trivial function that multiplies two integers:

3. Afterwards save and hit Ctrl+B (or Project > Build All) to build the library. If cygwin is on your path, you should see a “Release” folder in your project containing the file “mymath.dll”.

4. For windows to find the shared library, you need to add the directory containing the .dll to your path. On Vista this can be done via: Control Panel > User Accounts > User Accounts > Change my environment variables.

5. Exit and restart Eclipse after changing the PATH. Otherwise the changes will not be picked up.

Using a Shared Library with CDT

Follow these instructions to use a shared library in a “managed make” CDT project.

1. File > New > Project > C Project > Next. Project name: example. Project type: Executable; Empty Project. Hit Finish.

2. In that project create a file named example.c with the following content:

3. Save and hit Ctrl+B to build the project. The second line will have an error: “mymath.h: No such file or directory”. We now have to adjust the compiler and linker settings so that the mymath.h / mymath.dll files are found during the build.

4. Select the “example” folder in the Project Explorer. Select “Project > Properties” from the menu. A dialog comes up. In the tree on the left open: “C/C++ General > Paths and Symbols”. In the “Languages” list, pick “GNU C”. Then hit “Add”. Enter the cygwin-style path to the “mymath” project: /cygdrive/c/workspace/mymath

Caution: When entering the path, don’t use the “Workspace” or “File system” buttons because the resulting path will not be compatible with cygwin’s make.

5. In the same dialog select: C/C++ Build > Settings in the tree on the left. In the “Tool Settings” tab find: “Cygwin C Linker > Libraries”. Hit the “+” icon in the “Libraries” section and add the name of the library: mymath

Caution: if your shared library starts with lib, omit the ‘lib’ prefix (i.e. libfoo becomes foo)

Hit the “+” icon in the “Library search path” section and add the path to the folder containing the shared library: /cygdrive/c/workspace/mymath/Debug

Hit OK.

6. You will be asked to rebuild the project. Answer “Yes”, but for some reason this will not rebuild your project. Hit Ctrl+B to rebuild. The error will go away.

Note: ignore the “unresolved inclusion” warning. It seems that CDT has trouble resolving cygwin-style paths. The generated make-file however will work as expected.

7. Select “example” in the Project Explorer. Right-click > Run As > Local C/C++ Application. At this point you see the result of the multiplication on the console. That means that the shared library was found and used successfully:

Kind regards,
Elias.