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

[Chris Wilson]

 src/FAQ.mdwn |   33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

New commits:
commit 56936db886bd7768cf48a7b7886875a39694e0a3
Author: Chris Wilson <chris at chris-wilson.co.uk>
Date:   Sun Nov 16 21:34:55 2008 +0000

    [FAQ] Add a howto trace entry.
    
    Answer the question "My application's slower than I think it should be.
    What can I do to help the cairo community find the problem?"

diff --git a/src/FAQ.mdwn b/src/FAQ.mdwn
index 35d6b60..666ff2a 100644
--- a/src/FAQ.mdwn
+++ b/src/FAQ.mdwn
@@ -342,3 +342,36 @@ aligned with integer positions on the device-pixel grid. And the
 easiest way to do that is to use an identity transformation,
 (`cairo_identity_matrix`), and construct the path by calling
 `cairo_rectangle` with integer values.
+
+<h2 id="profiling">My application's slower than I think it should be.
+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.
+
+<h3>How to generate a trace:</h3>
+
+After installing Cairo from git, a 1.9 snapshot or a later release the cairo-trace utility will be available.
+
+	$ cairo-trace
+	usage: cairo-trace [--no-file|--verbose] command
+	cairo-trace will generate a log of all calls made by command to
+	cairo. This log will be stored in a file in the local directory
+	called command.$pid.trace.
+	Whatever else happens is driven by its argument:
+	--flush      - Flush the output trace after every call.
+	--verbose    - Show the trace on stdout.
+	--no-file    - Disable the creation of an output file.
+	--no-callers - Do not lookup the caller address/symbol/line whilst tracing.
+
+That is performing
+
+	$ cairo-trace /path/to/my/app arg1 arg2 ... argn
+
+will generate an output file called ./app.$pid.trace.