# The &kcachegrind; Handbook

## Introduction

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.

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.

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

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).

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).

&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.

## Using &kcachegrind;

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

### Quickstart Examples

Simply run it!

### Features of &kcachegrind;

Supports: arbitrary events, function grouping

### General Guidelines

Effective Profiling...

### Tutorial

A profiling session on &kcachegrind;.

## Command Reference

### The main &kcachegrind; window

#### The File Menu

&Ctrl;N File New

- Creates a new document

&Ctrl;S File Save

- Saves the document

&Ctrl;Q File Quit

- Quits &kappname;

## Questions and Answers

&reporting.bugs; &updating.documentation;

&kcachegrind; looks cool. But I don't understand it. What is it useful for?

&kcachegrind; is a helpful at a later stage in software development, called Profiling. If you don't develop applications, you don't need &kcachegrind;.

I get compile errors, what could be the problem?

Often, your &Qt;installation hasn't &kde; support.

## Credits and License

&kappname;

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 KCachegrind would exist. A lot of ideas for this &GUI; were from them, too.

And thanks for all the bug reports/suggestions from different users. Last but not least, thanks to

- &kde;, the wonderful Application framework,

- &Qt;, the perfect &GUI; toolkit

- &Linux;, the definitive OS

&underFDL;

## Installation

### How to obtain &kcachegrind;

&kcachegrind; has its homepage at http://www.weidendorfers.de/kcachegrind. Look there for further installation and compile instructions.

### Requirements

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.

### Compilation and Installation

&install.compile.documentation;

### Configuration

All configuration options are either in the configuration dialog or in the context popup menus of the graphs.

&documentation.index;