--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tracefw/tracecompiler/tracecompiler/readme.txt	Tue Aug 31 16:45:49 2010 +0300
@@ -0,0 +1,75 @@
+------------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.