9.3.5.9 Creating an Import Library

If a Microsoft-style import library API.lib or a GNAT-style import library libAPI.dll.a or libAPI.a is available with API.dll you can skip this section. You can also skip this section if API.dll or libAPI.dll is built with GNU tools as in this case it is possible to link directly against the DLL. Otherwise read on.

The Definition File

As previously mentioned, and unlike Unix systems, the list of symbols that are exported from a DLL must be provided explicitly in Windows. The main goal of a definition file is precisely that: list the symbols exported by a DLL. A definition file (usually a file with a .def suffix) has the following structure:

    [LIBRARY `name`]
    [DESCRIPTION `string`]
    EXPORTS
       `symbol1`
       `symbol2`
       ...

`LIBRARY `name`'

This section, which is optional, gives the name of the DLL.

`DESCRIPTION `string`'

This section, which is optional, gives a description string that will be embedded in the import library.

`EXPORTS'

This section gives the list of exported symbols (procedures, functions or variables). For instance in the case of API.dll the EXPORTS section of API.def looks like:

         EXPORTS
            some_var
            get

Note that you must specify the correct suffix (@`nn') (see Windows Calling Conventions) for a Stdcall calling convention function in the exported symbols list.

There can actually be other sections in a definition file, but these sections are not relevant to the discussion at hand.

GNAT-Style Import Library

To create a static import library from API.dll with the GNAT tools you should proceed as follows:

• Create the definition file API.def (see The Definition File). For that use the dll2def tool as follows:

           $ dll2def API.dll > API.def
  

  dll2def is a very simple tool: it takes as input a DLL and prints to standard output the list of entry points in the DLL. Note that if some routines in the DLL have the Stdcall convention (Windows Calling Conventions) with stripped @`nn' suffix then you'll have to edit api.def to add it, and specify `-k' to `gnatdll' when creating the import library.

  Here are some hints to find the right @`nn' suffix.

  • If you have the Microsoft import library (.lib), it is possible to get the right symbols by using Microsoft dumpbin tool (see the corresponding Microsoft documentation for further details).

                  $ dumpbin /exports api.lib
    

  • If you have a message about a missing symbol at link time the compiler tells you what symbol is expected. You just have to go back to the definition file and add the right suffix.
• Build the import library libAPI.dll.a, using gnatdll (see Using gnatdll) as follows:

           $ gnatdll -e API.def -d API.dll
  

  gnatdll takes as input a definition file API.def and the name of the DLL containing the services listed in the definition file API.dll. The name of the static import library generated is computed from the name of the definition file as follows: if the definition file name is xyz`.def`, the import library name will be lib``xyz`.a`. Note that in the previous example option `-e' could have been removed because the name of the definition file (before the '.def' suffix) is the same as the name of the DLL (Using gnatdll for more information about gnatdll).

Microsoft-Style Import Library

With GNAT you can either use a GNAT-style or Microsoft-style import library. A Microsoft import library is needed only if you plan to make an Ada DLL available to applications developed with Microsoft tools (Mixed-Language Programming on Windows).

To create a Microsoft-style import library for API.dll you should proceed as follows:

• Create the definition file API.def from the DLL. For this use either the dll2def tool as described above or the Microsoft dumpbin tool (see the corresponding Microsoft documentation for further details).
• Build the actual import library using Microsoft's lib utility:

           $ lib -machine:IX86 -def:API.def -out:API.lib
  

  If you use the above command the definition file API.def must contain a line giving the name of the DLL:

           LIBRARY      "API"
  

  See the Microsoft documentation for further details about the usage of lib.