------------TraceCompiler------------

----What is TraceCompiler?----

TraceCompiler will find OST (Open System Trace) traces from source files and generate needed headers and decode files for them

during component compilation time.

----What are OST traces?----

Open System Trace traces. Macros can be found from the header OpenSystemTrace.h. OST is a binary tracing concept for good performance

and run-time activation of traces.

----How to set up TraceCompiler?----

Remove comments before exports from group folder bld.inf

When compiled from the group folder, will export itself to /epoc32/tools folder.

Usually TraceCompiler is already integrated to Symbian build system, so there is no need to run TraceCompiler separately. Symbian build system calls 

TraceCompiler automatically during component compilation. 

If TraceCompiler is not integrated to build system but is needed to be run automatically when building a component

abld.pl in /epoc32/tools/ needs to be changed to call tracecompiler.pl file. Note that the change might already be there.

Change is done after a line like this:

  "foreach $LoopBld (@Blds) {"

And the change is this: (First line is comment)

	# Add the TraceCompiler once to the Calls array when TARGET is called

	$Command eq "TARGET" and not scalar grep(/tracecompiler\.pl/,@Calls) and push @Calls, "perl /epoc32/tools/tracecompiler.pl $Plat $Program";

----How to use TraceCompiler?----

Usually TraceCompiler is already integrated to Symbian build system, so there is no need to run TraceCompiler separately. Symbian build system calls 

TraceCompiler automatically during component compilation. 

If there is need to run TraceCompiler manually, it can be done following way:

   perl /epoc32/tools/tracecompiler.pl <platform> [program]

   For example: perl /epoc32/tools/tracecompiler.pl armv5

----How to actually get the traces?----

Open System Trace macros use Symbian BTrace framework to forward the traces. To get these traces, you must implement a trace handler which will

register itself to the Symbian BTrace using command BTrace::SetHandler( MyHandler ). Then it's up to you what to do with the traces.

----What is happening in TraceCompiler?----

1. tracecompiler.pl first runs a Java check to ensure that Java 1.5 or newer is found from the system. If this fails, tracecompiler.pl will exit.

   If Java check is OK, tracecompiler.pl opens a "abld.bat" file which is generated by command "bldmake bldfiles". From that file, a path to

   MAKEFILE generated by "bldmake bldfiles" is searched. This MAKEFILE is then opened and is parsed for a list of project MMP files. These MMP

   files are then forwarded to the tracecompiler_parse_mmp.pl script.

2. tracecompiler_parse_mmp.pl gets a MMP file as a parameter. It parses the MMP file for UID of the component and paths to all the source files.

	 NOTE that MACROS are NOT supported! If UID cannot be found from the MMP file, tracecompiler_parse_mmp.pl will exit. If UID is found,

	 TraceCompiler Java application is started and the component UID is given to it as a parameter. After it's started, component name, the path

	 to the MMP file of the component and a list of source paths are send to STDOUT of TraceCompiler Java application. When all source paths are

	 send, tracecompiler_parse_mmp.pl sends end tag "*ENDOFSOURCEFILES*" to TraceCompiler so it knows all the sources are then sent.

3. TraceCompiler Java application listens to STDIN for component name, MMP file path and the paths to the source files. When it receives

   "*ENDOFSOURCEFILES*" tag, it starts processing the source files. It finds all OST traces from the source files and generates needed headers

   for the application to compile properly. It also generates autogen header and Symbian Dictionary file from the traces.