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 RVCT 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,

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

while

..\bwins\ is used for WINSCW .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 .def files are expected to be in:

• directory ..\bwins\ for platforms WINSCW, CW_IDE, VS6 and VS2003

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

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

For example:

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

Note that the platform name macros used with #if defined(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 WINSCW, 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 WINSCW 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 ARMv5, then ARMv5_ABIv1 import libraries will be created.

• if a project is built for ARMv5_ABIv2, then ARMv5_ABIv2 import libraries will be created.