<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kcachegrind '<application>KCachegrind</application>'>
  <!ENTITY cachegrind "<application>Cachegrind</application>">
  <!ENTITY valgrind "<application>Valgrind</application>">
  <!ENTITY kappname "&kcachegrind;">
  <!ENTITY package "kdesdk">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<!-- ................................................................ -->

<book lang="&language;">

<bookinfo>
<title>The &kcachegrind; Handbook</title>

<authorgroup>
<author>
<firstname>Josef</firstname>
<surname>Weidendorfer</surname>
<affiliation>
<address><email>Josef.Weidendorfer@gmx.de</email></address>
</affiliation>
</author>
</authorgroup>

<copyright>
<year>2002</year>
<holder>Josef Weidendorfer</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>

<date>2003-09-18</date>
<releaseinfo>0.4.3</releaseinfo>

<abstract>
<para>
&kcachegrind; is a &kde; Frontend for &cachegrind;, part of
&valgrind;.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdesdk</keyword>
<keyword>Cachegrind</keyword>
<keyword>Valgrind</keyword>
<keyword>Profiling</keyword>
</keywordset>

</bookinfo>


<chapter id="introduction">
<title>Introduction</title>

<para>
When you develop a program, usually one of the last steps is to make
it as fast as possible (but still correct!).  You don't want to waste
your time, optimizing functions rarely used.  So you need to know in
which part of your program most of the time is spent.
</para>

<para>
This is called Profiling. The program is run in control of a profiling
tool, which gives you a trace of the execution run.  After examination
of the trace, you probably know where to optimize and afterwards you
verify the optimization success again with another profile run.
</para>

<para>
Most known is the GCC profiling tool <application>gprof</application>:
You need to compile your program with option <option>-pg</option>;
running the program generates a file <filename>gmon.out</filename>,
which can be transformed into human readable form with
<command>gprof</command>. The disadvantage is the needed compilation
step for a prepared executable, which has to be statically linked.
</para>

<para>
Another profiling tool is &cachegrind;, part of &valgrind;.  It uses
the processor emulation of &valgrind; to run the executable, and
catches all memory accesses for the trace. The program does not need
to be recompiled; it can use shared libraries and plugins, and the
profile measuring doesn't influence the trace results.  The trace
includes the number of instruction/data memory accesses and 1st/2nd
level cache misses, and relates it to source lines and functions of
the run program (a disadvantage is the slowdown involved the the
processor emulation, it's unfortunately around 50 times slower).
</para>

<para>A patch for &valgrind; 1.0.x sources adds call tree tracing,
&ie; how the functions call each other and how many events happen
while running a function (including all called functions).
</para>

<para>
&kappname; is a visualization tool for the profiling data generated by
&cachegrind;. It is strongly advised to add support for call tree
tracing into &cachegrind;, because &kcachegrind; is much more useful
this way.
</para>
</chapter>

<chapter id="using-kcachegrind">
<title>Using &kcachegrind;</title>

<note>
<para>
Every widget in &kcachegrind; has <quote>Whats' this</quote> help.  If
you don't want to search this documentation, use these!
</para>
</note>

<sect1>
<title>Quickstart Examples</title>


<para>Simply run it!</para>
</sect1>

<sect1 id="features">
<title>Features of &kcachegrind;</title>

<para>Supports: arbitrary events, function grouping</para>
</sect1>

<sect1 id="guidelines">
<title>General Guidelines</title>

<para>Effective Profiling...</para>

</sect1>
<sect1 id="tutorial">
<title>Tutorial</title>

<para>A profiling session on &kcachegrind;.</para>

</sect1>
</chapter>

<chapter id="commands">
<title>Command Reference</title>

<sect1 id="kcachegrind-mainwindow">
<title>The main &kcachegrind; window</title>
<para></para>

<sect2>
<title>The <guimenu>File</guimenu> Menu</title>
<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo>&Ctrl;<keycap>N</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice></term>
<listitem><para><action>Creates a new document</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo>&Ctrl;<keycap>S</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Save</guimenuitem>
</menuchoice></term>
<listitem><para><action>Saves the document</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo>&Ctrl;<keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits</action> &kappname;</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

</sect1>
</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">
<qandaentry>
<question>
<para>&kcachegrind; looks cool. But I don't understand it. 
What is it useful for?</para>
</question>
<answer>
<para>&kcachegrind; is a helpful at a later stage in software development,
called Profiling. If you don't develop applications, you don't need
&kcachegrind;.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I get compile errors, what could be the problem?</para>
</question>
<answer>
<para>Often, your &Qt;installation hasn't &kde; support.
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>

<chapter id="credits">


<title>Credits and License</title>

<para>
&kappname;
</para>
<para>
Thanks to Julian Seward for its excellent &valgrind;, and Nicholas
Nethercote for the &cachegrind; addition. Without these programs,
neither the call tree patch for &valgrind; nor
<application>KCachegrind</application> would exist.  A lot of ideas
for this &GUI; were from them, too.
</para>
<para>
And thanks for all the bug reports/suggestions from different
users. Last but not least, thanks to
<itemizedlist>
<listitem><para>&kde;, the wonderful Application framework,</para>
</listitem>
<listitem><para>&Qt;, the perfect &GUI; toolkit</para>
</listitem>
<listitem><para>&Linux;, the definitive <acronym>OS</acronym></para>
</listitem>
</itemizedlist>
</para>

&underFDL;        	 <!-- FDL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kcachegrind">
<title>How to obtain &kcachegrind;</title>

<para>
&kcachegrind; has its homepage at
<ulink url="http://www.weidendorfers.de/kcachegrind">
http://www.weidendorfers.de/kcachegrind</ulink>.  Look there for
further installation and compile instructions.
</para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>
In order to successfully use &kcachegrind;, you need &kde; 3.x.  For
generating profile traces, &cachegrind; is needed. To allow for the
most interesting visualization options of &kcachegrind;, apply the
call-tree patch from the &kcachegrind; homepage to your &valgrind;
sources.
</para>
</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

&install.compile.documentation;

</sect1>

<sect1 id="configuration">
<title>Configuration</title>

<para>All configuration options are either in the configuration dialog
or in the context popup menus of the graphs.
</para>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->













