gnatdll is a tool to automate the DLL build process once all the Ada
and non-Ada sources that make up your DLL have been compiled.
gnatdll is actually in charge of two distinct tasks: build the
static import library for the DLL and the actual DLL. The form of the
gnatdll command is
$ gnatdll [ switches ] list-of-files [ -largs opts ]
list-of-files is a list of ALI and object files. The object
file list must be the exact list of objects corresponding to the non-Ada
sources whose services are to be included in the DLL. The ALI file list
must be the exact list of ALI files for the corresponding Ada sources
whose services are to be included in the DLL. If
missing, only the static import library is generated.
You may specify any of the following switches to
Build a non-relocatable DLL at
address is not
specified the default address
0x11000000 will be used. By default,
when this switch is missing,
gnatdll builds relocatable DLL. We
advise the reader to build relocatable DLL.
Set the relocatable DLL base address. By default the address is
Binder options. Pass
opts to the binder.
dllfile is the name of the DLL. This switch must be present for
gnatdll to do anything. The name of the generated import library is
obtained algorithmically from
dllfile as shown in the following
xyz.dll, the import library name is
libxyz.dll.a. The name of the definition file to use (if not specified
-e) is obtained algorithmically from
as shown in the following example:
xyz.dll, the definition
file used is
deffile is the name of the definition file.
Generate debugging information. This information is stored in the object
file and copied from there to the final DLL file by the linker,
where it can be read by the debugger. You must use the
-g switch if you plan on using the debugger or the symbolic
Help mode. Displays
gnatdll switch usage information.
gnatdll to search the
dir directory for source and
object files needed to build the DLL.
(Search Paths and the Run-Time Library (RTL)).
@`nn' suffix from the import library’s exported
names, but keeps them for the link names. You must specify this
option if you want to use a
Stdcall function in a DLL for which
@`nn' suffix has been removed. This is the case for most
of the Windows NT DLL for example. This option has no effect when
-n option is specified.
The list of ALI and object files used to build the DLL are listed in
file, instead of being given in the command line. Each line in
file contains the name of an ALI or object file.
No Import. Do not create the import library.
Quiet mode. Do not display unnecessary messages.
Verbose mode. Display extra information.
Linker options. Pass
opts to the linker.
As an example the command to build a relocatable DLL from
api.adb has been compiled and
api.def created is
$ gnatdll -d api.dll api.ali
The above command creates two files:
libapi.dll.a (the import
api.dll (the actual DLL). If you want to create
only the DLL, just type:
$ gnatdll -d api.dll -n api.ali
Alternatively if you want to create just the import library, type:
$ gnatdll -d api.dll
gnatdllbehind the Scenes
This section details the steps involved in creating a DLL.
does these steps for you. Unless you are interested in understanding what
goes on behind the scenes, you should skip this section.
We use the previous example of a DLL containing the Ada package
to illustrate the steps necessary to build a DLL. The starting point is a
set of objects that will make up the DLL and the corresponding ALI
files. In the case of this example this means that
api.ali are available. To build a relocatable DLL,
gnatdllbuilds the base file (
api.base). A base file gives the information necessary to generate relocation information for the DLL.
$ gnatbind -n api $ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base
In addition to the base file, the
gnatlink command generates an
api.jnk which can be discarded. The
gnatlink to generate the routines
DllMainCRTStartup that are called by the Windows loader when the DLL
is loaded into memory.
dlltool(see Using dlltool) to build the export table (
api.exp). The export table contains the relocation information in a form which can be used during the final link to ensure that the Windows loader is able to place the DLL anywhere in memory.
$ dlltool --dllname api.dll --def api.def --base-file api.base \\ --output-exp api.exp
gnatdllbuilds the base file using the new export table. Note that
gnatbindmust be called once again since the binder generated file has been deleted during the previous call to
$ gnatbind -n api $ gnatlink api -o api.jnk api.exp -mdll -Wl,--base-file,api.base
gnatdllbuilds the new export table using the new base file and generates the DLL import library
$ dlltool --dllname api.dll --def api.def --base-file api.base \\ --output-exp api.exp --output-lib libAPI.a
gnatdllbuilds the relocatable DLL using the final export table.
$ gnatbind -n api $ gnatlink api api.exp -o api.dll -mdll
dlltool is the low-level tool used by
gnatdll to build
DLLs and static import libraries. This section summarizes the most
dlltool switches. The form of the
$ dlltool [`switches`]
dlltool switches include:
Read the base file
basefile generated by the linker. This switch
is used to create a relocatable DLL.
Read the definition file.
Gives the name of the DLL. This switch is used to embed the name of the
DLL in the static import library generated by
dlltool with switch
@`nn' from exported names
(Windows Calling Conventions
for a discussion about
dlltool switches with a concise description.
Generate an export file
exportfile. The export file contains the
export table (list of symbols in the DLL) and is used to create the DLL.
Generate a static import library
assembler-name as the assembler. The default is