[cairo-commit] [cairo-www] src/FAQ.mdwn

[Carl Worth]

 src/FAQ.mdwn |   44 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 33 insertions(+), 11 deletions(-)

New commits:
commit 17f1050bc6132f78b9497bbd3e9ba0f876dfc065
Author: Carl Worth <cworth at cworth.org>
Date:   Fri Jun 12 14:28:14 2009 -0700

    FAQ: Expand a bit more on cairo-perf-trace
    
    Give example of how to run cairo-perf-trace explicitly on a trace
    file. Also mention how cairo-traces repository can be checked out
    into perf/cairo-traces.

diff --git a/src/FAQ.mdwn b/src/FAQ.mdwn
index 8d94b92..632db15 100644
--- a/src/FAQ.mdwn
+++ b/src/FAQ.mdwn
@@ -348,13 +348,15 @@ easiest way to do that is to use an identity transformation,
 What can I do to help the cairo community find the problem?</h2>
 
 The first step in analysing any problem is constructing a reproducible
-test case. Cairo provides a cairo-trace utility (currently only available
-from the git development tree, but is planned for inclusion with Cairo 1.10).
-This utility records all Cairo calls made by an application and allows you,
-and everyone else in the community, to replay the exact same sequence. This
-trace can be reviewed by others and they may be able to suggest alternative
-methods of achieving the same results. Or it may provide the developers with
-a useful benchmark for improving Cairo.
+test case. Cairo provides a cairo-trace utility (currently only
+available from the git development tree and in the 1.9.2
+[snapshot](/snapshots) but also planned for inclusion with Cairo
+1.10).  This utility records all Cairo calls made by an application
+and allows you, and everyone else in the community, to replay the
+exact same sequence. This trace can be reviewed by others and they may
+be able to suggest alternative methods of achieving the same
+results. Or it may provide the developers with a useful benchmark for
+improving Cairo.
 
 <h3>How to generate a trace:</h3>
 
@@ -377,10 +379,30 @@ After installing Cairo from git, a 1.9 snapshot or a later release the cairo-tra
 
 That is performing
 
-	$ cairo-trace /path/to/my/app arg1 arg2 ... argn
+	$ cairo-trace any-application
 
-will generate an output file called ./app.$pid.trace. If you want to simply record a trace to share, then use
+and then operating the application as desired will generate an output
+file called any-application.$pid.trace.
 
-	$ cairo-trace --profile /path/to/my/app arg1 arg2 ... argn
+If you want to record a trace to share with others for performance
+measurement, then use the --profile option to cairo-trace as follows:
 
-A compilation of "interesting" traces can be found [here](:http://cgit.freedesktop.org/cairo-traces), which are automatically run by the perf/cairo-perf-trace benchmarking tool.
+	$ cairo-trace --profile any-application
+
+This eliminates the extra caller information from the trace, (which
+reduces overhead when replaying), and compresses the output,
+(decompress with the "lzma -cd").
+
+To benchmark the performance of a trace, run:
+
+	$ cairo-perf-trace application.trace
+
+which will replay the trace several times against multiple backends
+and report the time required for replay against each backend.
+
+A compilation of "interesting" traces can be found in the
+[cairo-traces
+repositroy](http://cgit.freedesktop.org/cairo-traces). By checking
+this repository out to perf/cairo-traces in the cairo source
+directory, these traces will be automatically run by
+"cairo-perf-trace" (with no arguments) as well as by "make perf".