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
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.
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.