deffile

deffile filename

Use the deffile statement to override the default linker definition file for the project.

A .def file specifies associations between exported function names and their ordinal export number. It is used by the linker when constructing a DLL and (where applicable) when constructing its associated import library.

The assignment of ordinals must be controlled by a .def file in two situations:

• A polymorphic interface DLL must export a particular function as ordinal 1. In this case, the .def file is used to specify this association, while other exported functions may have a random order.

• A re-released DLL must be used by clients built against the old version. In this case, the .def file is used to ensure that all functions exported by the old version of the DLL are exported with the same ordinal by the new version.

For many polymorphic DLLs, a special target type is provided so that the build tools can ensure that the correct function is exported as ordinal 1. Where a special target type is provided, the .def file can be dispensed with.

.def files are sometimes colloquially referred to as freeze files, because they freeze the association between name and ordinal, for exported functions.

The GNU and Microsoft tool chains use different schemes for mangling the names of exported functions. This means that .def files of the same name must be differentiated by storing them in separate directories.

Conventionally,

..\bmarm\ is used for ARM .def files,

while

..\bwins\ is used for WINS .def files.

By default, the frozen .def file takes its basename from the basename of the target for the project.

Where the default frozen .def file is overridden by the deffile statement, a path to the file can be specified as part of the filename.

If no path is specified, the file will be expected to be in:

• directory ..\bwins\ for platforms WINS and VC6

• directory ..\bmarm\ for the ARM platform.

If a path is specified, place the deffile statement within #ifdefined(identifier) so that the same file will not be used during both ARM and WINS builds.

For example:

#if defined(WINS)
deffile-stmt
#else if defined(ARM)
deffile-stmt
#endif

Note that the platform name macros used with #ifdefined(identifier) must be in upper-case.

In most cases, the functions exported from a DLL depend on the build variant. This is common because descriptor class names depend on whether the build is wide or narrow. For such DLLs, different .def files—differentiated by the -u suffix—are used. Although narrow builds are no longer supported, the -u suffix is still in use to maintain backward compatibility with previous versions of the build tools. This suffix behaviour can be removed by using nostrictdef.

Note too that under WINS, when using an exedll target type, the first export is the one which will be called when the DLL is loaded, so you should use a .def file for the WINS variant.

Makefiles create the import library associated with an executable (where applicable) directly from the frozen .def file, so only frozen exported functions will appear in the import library and only these exported functions can be linked against by other components.

For ARM platforms, import libraries for compatible ABIs are also created.

For example

• if a project is built for ARMI, then ARMI, THUMB and ARM4 import libraries will be created

• and if a project is built for THUMB, then ARMI and THUMB import libraries will be created.