How to use the post-linker (elf2e32)

The post-linker is a Symbian-specific build tool. Its principal function is to create executables (DLLs and EXEs) in the particular format required by Symbian OS, known as the E32Image format. Commercial compiler and linkers, such as ARM's RVCT and GNU GCC, cannot directly generate that format. Such compilers do however support a standard output format called the Executable and Linking Format (ELF) (defined at http://www.caldera.com/developers/gabi/). A tool is therefore needed to convert from the ELF format into the E32Image format, and this is the key role of the post-linker. The tool also contains the functionality to maintain and create the DEF files used for freezing the exports of libraries.

In ordinary use, the post-linker is not used directly by users. It is called from the makefiles generated by abld on the command line, or from the build commands of an IDE.

The tool can also be used to output a description of an existing E32Image file for analysis.

The post-linker is introduced in Symbian OS v9.1. It is only used for native targets that use version 2 of the ARM ABI, not for ARMV5 in ABIv1 mode.

Readers of this document should also refer to:

• the elf2e32 command syntax reference page

• Troubleshooting post-linker (elf2e32) errors

The figure below shows the position of the post-linker in the architecture of the build tool chain:

The ELF format object file is known as a Dynamic Shared Object (DSO) file. There are two types of DSO on the diagram: DSO (executable) indicates a file containing executable instructions; DSO (library) means a DSO that plays a similiar role to an import library (.LIB) file in previous tool chains. .LIB files are not used by the toolchain; instead, the library DSOs hold the information required for the linker to link to the correct ordinals to the dll. The .LIB files cannot be used by the ABIv2 toolchain, and the .DSO files cannot be used by the ABIv1 toolchain.

Note: When you are building on both, the ARM and WINSCW targets, it is recommended that the .lib extension be used to import libraries. See the note in the library section for more information.

The compiler and linker, such as those supplied by the ARM RVCT, take source code, static libraries, and as library DSO files as input, and output an ELF executable file.

The output from this stage can then be converted into the E32Image format by the post-linker. This conversion includes adding Symbian OS-specific information. This information can include:

• whether the file is a DLL or an EXE

• platform security information for capabilities, secure ID, and vendor ID. See Symbian OS Guide/Platform security/Symbian OSv9.0 Security Architecture for more information.

• whether a process should have a fixed address. See Fixed processes for more information.

• initial and reserved process heap size. See Memory Management concepts for more information.

• initial process stack size.

• file UIDs. See How to use UIDs for more information.

The Symbian OS-specific options are specified as command-line arguments to the post-linker. In ordinary use, values for these arguments are derived by the abld/makmake tools from the MMP file of the project being built.

The post-linker also has responsibility for outputing any DSO library files and DEF files required for the project. Again, the requirements for these are specified on the command-line to the post-linker, and in ordinary use derived from the project's MMP file.

The following sections describe the uses of the tool.

This section describes how elf2e32 is called when creating EXEs, DLLs, EXEXPs (EXE with exports), and custom targets.

Note elf2e32 is not used for creating static libraries (.lib). These are constructed by putting object files output by the compiler into archives using the GCC ar tool

The following shows an example of using the tool to create an EXE (without any exports):

> elf2e32 --targettype=EXE --elfinput="\epoc32\build\foo\armv5\urel\foo.exe" --linkas=foo{000a0000}[10011235].exe --libpath="\epoc32\release\armv5\lib" --output="\epoc32\release\armv5\urel\foo.exe" --uid1=0x1000007A --uid2=0x10011234 --uid3=0x10011235 --capability=ReadUserData+WriteUserData --sid=0x10011235 --vid=0x70000010

This outputs foo.exe. Note that:

• --capability, --sid, and --vid specify platform security capabilities and IDs.

• --elfinput specifies the ELF DSO executable output from the compiler/linker

• --libpath specifies the paths that should be searched for any required import libraries. Whether any are needed depends on whether the DSO executable imported any symbols from any other executables.

• --linkas specifies the internal name used in the image file for the executable.

• --output specifies the path to the output EXE file

• --targettype specifies that an EXE (rather than a DLL or import library) should be output

• --uid1, --uid2, and --uid3 specify the file's UIDs. For an EXE, UID1 is always 0x1000007A.

The following shows an example of using the tool to create a DLL:

> elf2e32 --targettype=DLL --elfinput="\epoc32\build\foo\armv5\urel\foo.dll" --definput=\foo\eabi\foou.def --defoutput=\epoc32\build\foo\armv5\urel\foou.def --dso="\epoc32\release\armv5\lib\foo.dso" --linkas=foo{000a0000}[10011237].dll --libpath="\epoc32\release\armv5\lib" --output="\epoc32\release\armv5\urel\foo.dll" --uid1=0x10000079 --uid2=0x10011236 --uid3=0x10011237 --capability=ReadUserData+WriteUserData --sid=0x10011235 --vid=0x70000010

This outputs foo.dso, foo.dll, and foou.def. Note that:

• --targettype specifies that an DLL should be output

• --elfinput specifies the ELF DSO executable output from the compiler/linker

• --definput specifies an input DEF file that defines the DLL's exports.

  Typically in Symbian OS development, DEF files are maintained for DLLs, so that the order of the exports remains the same from one build to another (see How to control binary compatibility).

  If the DLL is under early stages of development, and control of exports is not yet an issue, then an input DEF file does not have to be specified.

• --defoutput specifies the path to an output DEF file.

  Specifying this argument causes elf2e32 to create a DEF file listing the ELF input's exports.

  elf2e32 will compare this generated file against any input DEF file specified with --definput. Any differences between these are handled as follows:

  • If the input DEF file specifies exports that are not found in the ELF input, then the tool reports an error.

    If you are not concerned with maintaining compatibility, use the --unfrozen option. This will stop the tool reporting this error.

  • If a symbol is marked as ABSENT in the DEF file, but present in the ELF input, the tool outputs a warning.

    The symbol is written to output def file, retaining the ordinal number as of the absent symbol.

  • Differences are annotated in the output DEF file as follows:

    • Groups of new exports (i.e. exports not specified in an input def file) are indicated with a comment ; NEW:.

    • If an export was specified in an input DEF file, but no longer exists in the executable, this is indicated with a comment ; MISSING:.

  To make any necessary adjustments to the source DEF file, a developer can use the efreeze tool.

• --dso specifies where a LIB file constructed by the tool should be output.

• --libpath specifies the paths that should be searched for any required import libraries. Whether any are needed depends on whether the DSO executable imported any symbols from any other executables.

• --linkas specifies the internal name used in the image file for the executable.

• --output specifies the path to the output DLL file

• --uid1, --uid2, and --uid3 specify the file's UIDs. For a DLL, UID1 is always 0x10000079.

• --capability, --sid, and --vid specify platform security capabilities and IDs.

The following options can also be used specifically with DLLs:

• --dlldata can be used to signal that the DLL is allowed to contain writeable static data. By default, DLLs are not allowed to contain such data.

• --sysdef is used with Symbian OS polymorphic DLL target types, such as PLUGIN (ECom plug-in DLLs) and ANI (Window server animation DLLs). Project files for these types of DLL do not have to specify an input DEF file: instead, the build tools (such as abld, makmake) are expected to know what exports are required for the target type.

  The --sysdef option allows the caller of elf2e32 to specify the required exported symbol without an input DEF file being specified with --definput. The following example force the specified _Z14NewApplicationv symbol to be exported at the ordinal 1 position.

  elf2e32  --targettype=APP --sysdef=_Z14NewApplicationv,1 --output=test.app --defoutput=testapp.def --elfinput=testapp.app --uncompressed --sid=0x10004264 --uid1=0x10000079 --uid2=0x10004262 --uid3=0x10004264 --vid=0x00000003 --capability=none

Symbian OS supports EXEs that have exports: the EXEXP target type. To create an executable of this type, use the options for an EXE, and add the options used for DLLs for specifying input and output DEF files, and for outputting an import library. For example:

> elf2e32 --targettype=EXEXP --elfinput="\epoc32\build\foo\armv5\urel\foo.exe" --definput=\foo\eabi\foou.def --defoutput=\epoc32\build\foo\armv5\urel\foou.def --dso="\epoc32\release\armv5\lib\foo.dso" --linkas=foo{000a0000}[10011235].exe --libpath=\epoc32\release\armv5\lib --output=\epoc32\release\armv5\urel\foo.exe --uid1=0x1000007A --uid2=0x10011234 --uid3=0x10011235 --capability=ReadUserData+WriteUserData --sid=0x10011235 --vid=0x70000010

This outputs foo.dso, foo.exe, and foou.def.

As with a DLL, if an EXEXP is under early stages of development, and control of exports is not yet an issue, then an input DEF file does not have to be specified.

The tool chain can convert existing static libraries or ELF executable files into Symbian OS executables. This is needed when third-parties supply libraries in these forms.

• --elfinput should specify the input file to be converted

• --targettype should not be specified

• --definput, specifying an input DEF file, is optional. It should be used when the executable has exports that have been frozen.

The following shows converting the static library foo.lib into foo.dll. A DSO library file foo.dso, and DEF file foou.def are also output.

> elf2e32 --elfinput=\epoc32\build\foo\armv5\urel\foo.lib --defoutput=\epoc32\build\foo\armv5\urel\foou.def --dso=\epoc32\release\armv5\lib\foo.dso --linkas=foo{000a0000}[10011237].dll --libpath=\epoc32\release\armv5\lib --output=\epoc32\release\armv5\urel\foo.dll --uid1=0x10000079 --uid2=0x10011236 --uid3=0x10011237 --capability=ReadUserData+WriteUserData --sid=0x10011235 --vid=0x70000010

The post-linker allows an DSO library file to be created from an input DEF file, without creating a DLL executable.

This is used in Symbian build tools to multiple components to be built without needing to handle dependencies between them. It is also used for the IMPLIB target type.

The following shows an example of using the tool for this purpose:

> elf2e32 --targetype=implib --definput=\foo\eabi\foou.def --dso=\epoc32\release\armv5\lib\foo.dso --linkas=foo{000a0000}[10011237].dll

This outputs foo.dso.

To output a description of an existing E32Image file to standard out, specify the file using the --e32input option.

The description includes sections on the executable's header, security properties (SID, VID, capabilities), imports, exports, code section, and data section. The output can be restricted to include just some of these sections by using the --dump option.

The following shows an example of using the tool for this purpose:

> elf2e32 --e32input=\epoc32\RELEASE\ARMV5\UDEB\swicertstoreplugin.dll --dump=h

This outputs a description of swicertstoreplugin.dll. The description includes just the section for the header, as h is specified to --dump. The output will be something like the following:

E32ImageFile 'D:\rdrive\epoc32\RELEASE\ARMV5\UDEB\swicertstoreplugin.dll
V2.01(538)      Time Stamp: 00e0d167,a9746080
EPOC Dll for ARMV4 CPU
Flags:  1200002b
Entry points are not called
Image header is format 2
Image is compressed using the DEFLATE algorithm
Uncompressed size 000001a8
Secure ID: 1020430c
Vendor ID: 70000001
Capabilities: 00000000 000ffffe
Exception Descriptor Offset:  00000011
Exception Index Table Base: 000080ac
Exception Index Table Limit: 000080b4
RO Segment Base: 00008001
RO Segment Limit: 000080b4
Export Description: Size=000, Type=00
Export description consistent
Module Version: 10.0
Imports are ELF-style
ARM EABI
Built against EKA2
Uids:           10000079 10009d8d 1020430c (f28e88cf)
Header CRC:     5256e096
File Size:      000001a8
Code Size:      000000b4
Data Size:      00000000
Compression:    101f7afc
Min Heap Size:  00001000
Max Heap Size:  00100000
Stack Size:     00002000
Code link addr: 00008000
Data link addr: 00000000
Code reloc offset:      00000188
Data reloc offset:      00000000
Dll ref table count: 1
        Offset  Size  Relocs #Relocs
Code    00009c 0000b4 000188 000008        +000000 (entry pnt)
Data    000000 000000
Bss            000000
Export  000134 000004                      (1 entries)
Import  000150

Other possible dump arguments are s for security properties; c for code section; d for data section; e for exports; and i for imports.