Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



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:


Overview

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

Post linker

Post linker

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.

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:

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.

[Top]


How to create executables

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


EXE

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:


DLL

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:

The following options can also be used specifically with DLLs:


EXEXP

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.


Custom target

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.

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

[Top]


How to create a DSO library file from a DEF file

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.

[Top]


How to dump an E32Image file

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.