KDev-Valgrind : User Documentation

KDev-Valgrind : User Documentation Damien Coppel Anthony Corbacho Lionel Duc Mathieu Lornac Sébastien Rannou Lucas Sarie This document is for developers wishing to use the plugin. It enables to understand in a simple and efficient way the process of installation, the usage of the module, and to take advantage of the features of the module. The KDev-Valgrind team - December 9, 2011 1

Description of the document Titre User documentation Date December 9, 2011 Mail kdevvalgrind 2012@labeip.epitech.eu In charge Sébastien RANNOU Version 1.3 Table of revisions Date Section(s) Commentaire March 2011 All Creation of the document April 2011 3.3 Modification of the git address on sbrk.org July 2011 All Update December 2011 6 Update The KDev-Valgrind team - December 9, 2011 2

Contents 1 Summary of the document 4 2 Introduction 4 2.1 Aim of EIP........................................ 4 2.2 Aim of KDev-Valgrind.................................. 4 3 Installation 4 3.1 Installation script..................................... 4 3.2 KDevPlatform and KDevelop.............................. 4 3.2.1 With packages.................................. 4 3.2.2 With sources................................... 5 3.3 KDev-valgrind...................................... 6 3.3.1 From the sources................................. 6 3.4 Vérification........................................ 6 4 Uninstallation 7 5 Language 7 6 Usage 8 6.1 Configuration....................................... 8 6.1.1 Global tab.................................... 8 6.1.2 Specific tabs................................... 9 6.2 Launch.......................................... 9 6.3 Result........................................... 10 6.3.1 Memcheck..................................... 10 6.3.2 Massif....................................... 11 6.3.3 Callgrind..................................... 12 6.3.4 Cachegrind.................................... 13 6.4 Interactions........................................ 13 7 FAQ 14 8 Links 14 9 Conclusion 14 The KDev-Valgrind team - December 9, 2011 3

1 Summary of the document The first part of the document explains how to install KDevelop and the plugin kdevvalgrind. There is no graphical installer for the current development version, but the plugin aims developers with some knowledge and this point won t be a problem for them. Later we ll provide packages for some distributions to make this process easier for classic users. Then the several actions to configure and to use the plugin will be detailed. A brief description of bugs and usual questions is available at the end of the document, as well as uselful links. 2 Introduction 2.1 Aim of EIP The EIP 1 is a two years project where students of the Epitech are working in group of 5 to N students on a project of their own reflexion. The primary goal of the final project of Epitech is to achieve a project as you would in a business context. In addition, it allows students to practice their managerial skills. 2.2 Aim of KDev-Valgrind KDev-Valgrind is a project aiming at create a plugin for the KDevelop environment. This plugin will integrate the Valgrind s tools in the IDE 2 and facilitate its use. Even if Valgrind is use by many developpers, there is curently no implementation in this IDE. The integration is a will of the KDevelop community and obvioulsy, it will be free 3. 3 Installation 3.1 Installation script An installation script is available 4 for the Ubuntu distribution as well as for Archlinux. This script enables to easily install KDevPlatform, KDevelop, and KDev-valgrind. However, an installation script won t cover all developer needs. Indeed it is difficult to handle different versions in that way and the uninstallation is totally dependant of the script which is not tolerable. That s why we have decided to create packages for major GNU/Linux distributions as well as distributions that we like. Inside a distribution, a package enables the update, installation and uninstallation of the plugin. This is a considerable plus for open source systems, we can t avoid that way. The integrity of sources is also handled, before unarchiving, a checksum inside the package is computed. Moreover, by registering dependancies of the plugin, the installation can t be in an invalid state. 3.2 KDevPlatform and KDevelop 3.2.1 With packages All GNU/Linux distribution have a package manager. This makes the installation process easier as well as updates. The installation of a package is done that way: Under Ubuntu : sudo apt-get install kdevelop 1 Epitech Innovative Project 2 Integrated Development Environment 3 Free as in freedom, not as in beer 4 http://redmine.sbrk.org/attachments/10/bootstrap.sh The KDev-Valgrind team - December 9, 2011 4

Under Fedora : sudo yum install kdevelop Under Archlinux : sudo pacman -S kdevelop 3.2.2 With sources We can locally install KDevelop directly from the sources of the git repository. This method is however more complex. The required dependencies are different among distributions, here are some examples: Under Fedora 13: kdelibs-devel kdebase-workspace-devel Under Ubuntu 11.04: git cmake gcc g++ kdelibs5-dev zlib1g-dev kdebase-workspace-dev The details for the different distributions are available on their wiki. Then we have to download the sources : git clone git://anongit.kde.org/kdevplatform $HOME/src/kdevplatform git clone git://anongit.kde.org/kdevelop $HOME/src/kdevelop It is necessary to compile and install KDevPlatform first (by specifying an installation path, here $HOME/kdevelop4 ). mkdir -p $HOME/src/kdevplatform/build cd $HOME/src/kdevplatform/build cmake -DCMAKE_INSTALL_PREFIX=$HOME/kdevelop4../ make make install Then with KDevelop : mkdir -p $HOME/src/kdevelop/build cd $HOME/src/kdevelop/build cmake -DCMAKE_PREFIX_PATH=$HOME/kdevelop4 -DCMAKE_INSTALL_PREFIX=$HOME/kdevelop4../ make make install Before running KDevelop, we need to specify the environment variable KDEDIRS : export KDEDIRS=$HOME/kdevelop4:/$KDEDIRS kbuildsycoca4 KDevelop is now ready to be start: $HOME/kdevelop4/bin/kdevelop If KDevelop is installed from the sources, the package manager wont automatically update it. However it is possible to update it in the following way: cd $HOME/src/kdevelop/build && make uninstall cd $HOME/src/kdevplatform/build && make uninstall cd $HOME/src/kdevplatform && git pull cd $HOME/src/kdevplatform/build && make && make install cd $HOME/src/kdevelop && git pull cd $HOME/src/kdevelop/build && make && make install kbuildsycoca4 The KDev-Valgrind team - December 9, 2011 5

3.3 KDev-valgrind Once KDevPlatform and KDevelop are installed, we can install the plugin. 3.3.1 From the sources The sources are available on the official repository of KDE or on our server sbrk.org. The official sources are often synchronized when the new versions on the other server are validated. Later the official server will be the only one used, but at that moment, only one member of the group has the necessary rights to commit. Sources from sbrk (for developpers): git clone git@sbrk.org:kdev-valgrind.git Official sources: git clone git://anongit.kde.org/kdev-valgrind Then we have to compile and install sources. These commands are using files from the $HOME/src/ folder, which depends of the path where sources where downloaded. mkdir -p $HOME/src/kdev-valgrind/build cd $HOME/src/php/build cmake -DCMAKE_INSTALL_PREFIX=$HOME/kdevelop4../ make make install export KDEDIRS=$HOME/kdevelop4:/usr kbuildsycoca4 Once installed, the plugin will be automatically detected by KDevelop upon the next startup. Updates are also simple to perform : cd $HOME/src/kdev-valgrind && git pull cd $HOME/src/kdev-valgrind/build && make && make install kbuildsycoca4 3.4 Vérification Once the plugin is installed, we can check that its loading is correctly made in KDevelop. In the tab Help->Loaded Plugins, a new line should appear as shown on the figure 1. Figure 1: Valgrind plugin correctly loaded The KDev-Valgrind team - December 9, 2011 6

4 Uninstallation In the same fashion it is very easy to remove the plugin : cd $HOME/src/kdev-valgring/build && make uninstall Upon the next startup of KDevelop, the plugin won t be available anymore. 5 Language The language of the plugin is defined according to the one set in the operating system. Thanks to the open source community, the plugin is already available in several languages. The locales that are currently supported are the following : ca, ca@valencia, en GB, es, et, fr, it, nds, nl, pt, pt BR, sv, uk. The KDev-Valgrind team - December 9, 2011 7

6 Usage 6.1 Configuration The plugin provides a global configuration tab, and a configuration tab per tool. The different configurations are accessible via the menu Run - Configure Launches as show on the figure 2. Figure 2: Configure launches 6.1.1 Global tab The global configuration of the plugin is available with the Valgrind line of the configuration menu. It can be common to all projects or specific to a few. This tab enables to define the path to the Valgrind binary (configured to default) which will be launched with parameters that can also be configured there. 3. Figure 3: Global configuration tab of Valgrind The KDev-Valgrind team - December 9, 2011 8

6.1.2 Specific tabs Each tool of the Valgrind suite has its own configuration tab. The tools Memcheck, Massif, Callgrind and Cachegrind are usable and configurable as shown of the Figure 4 Figure 4: Configuration tab of memcheck 6.2 Launch Once configured (the default configuration will work in most cases), we can launch the selected tool. We can launch the tool using the KDevelop menu( Run - Profile Launch->Valgrind ) as shown on the figure 5. Figure 5: Valgrind launch The KDev-Valgrind team - December 9, 2011 9

6.3 Result 6.3.1 Memcheck Memcheck is a memory error detector. It can detect the following problems that are common in C and C++ programs : Accessing memory you shouldn t, e.g. overrunning and underrunning heap blocks, overrunning the top of the stack, and accessing memory after it has been freed. Using undefined values, i.e. values that have not been initialised, or that have been derived from other undefined values. Incorrect freeing of heap memory, such as double-freeing heap blocks, or mismatched use of malloc/new/new[] versus free/delete/delete[] Overlapping src and dst pointers in memcpy and related functions. Memory leaks. Problems like these can be difficult to find by other means, often remaining undetected for long periods, then causing occasional, difficult-to-diagnose crashes. The different errors found by the tool will be displayed in a tree as shown on the Figure 6. The errors are also highlighted in the source code in order to get a clear view. Figure 6: Result of a call to the plugin The KDev-Valgrind team - December 9, 2011 10

6.3.2 Massif Massif is a heap profiler. It measures how much heap memory your program uses. This includes both the useful space, and the extra bytes allocated for book-keeping and alignment purposes. It can also measure the size of your program s stacks. Heap profiling can help you reduce the amount of memory your program uses. On modern machines with virtual memory, this can be used to speed up your program (a smaller program will interact better with your machine s caches and avoid paging) and if your program uses lots of memory, it will reduce the chance that it exhausts your machine s swap space. Also, there are certain space leaks that aren t detected by traditional leak-checkers, such as Memcheck s. That s because the memory isn t ever actually lost (a pointer remains to it) but it s not in use. Programs that have leaks like this can unnecessarily increase the amount of memory they are using over time. Massif can help identify these leaks. Importantly, Massif tells you not only how much heap memory your program is using, it also gives very detailed information that indicates which parts of your program are responsible for allocating the heap memory. In the configuration tab, you can also choose to use Massif visualizer to get a graphical view of the data. Figure 7: The tool massif used in combination with massif visualizer The KDev-Valgrind team - December 9, 2011 11

6.3.3 Callgrind Callgrind is a profiling tool that records the call history among functions in a program s run as a call-graph. By default, the collected data consists of the number of instructions executed, their relationship to source lines, the caller/callee relationship between functions, and the numbers of such calls. Optionally, cache simulation and/or branch prediction (similar to Cachegrind) can produce further information about the runtime behavior of an application. In the configuration tab, you can also choose to use KCachegrind to get a graphical view of the data. Figure 8: The tool callgrind used in combination with kcachegrind The KDev-Valgrind team - December 9, 2011 12

6.3.4 Cachegrind Cachegrind simulates how your program interacts with a machine s cache hierarchy and (optionally) branch predictor. It simulates a machine with independent first-level instruction and data caches, backed by a unified second-level cache. This exactly matches the configuration of many modern machines. These statistics are presented for the entire program and for each function in the program. You can also annotate each line of source code in the program with the counts that were caused directly by it. However, some modern machines have three levels of cache. For these machines (in the cases where Cachegrind can auto-detect the cache configuration) Cachegrind simulates the first-level and third-level caches. In the configuration tab, you can also choose to use KCachegrind to get a graphical view of the data. Figure 9: The tool cachegrind 6.4 Interactions It is possible to clic on the errors to go to the line of the error in the editing area. If the file is not open, it will automatically be open by the editor and the cursos go to the line specified by Valgrind. The KDev-Valgrind team - December 9, 2011 13

7 FAQ What can I do with KDev-Valgrind? Once finished, the plugin will bring all functionnalities offered by Valgrind inside KDevelop. Moreover, thanks to the computations made on the results, it will be easier to visualize and interprate Valgrind s output. Why sould I use KDev-Valgrind? The usage of the plugin enables C/C++ developers to save time during debugging by avoiding to run it in a console outside of the IDE. Which version of KDevelop is supported? The plugin is developped for the 4.x versions of KDevelop. Major changes were introduced between the version 3 and 4, the plugin is not working on older versions such as 3.x. Can we freely use KDev-Valgrind, under which license is it available? Yes, the plugin is totally free, it is developped under the GNU GPL license. modified and distributed. It can be Can we use the plugin in other IDEs? No, the plugin is made for KDevelop and won t run in other IDEs. However, if you want to port it to other projects, you are welcome. Can we install the plugin directly from the package manager? The plugin is in constant evolution and updates are frequent. The creation of dedicated packages will be made once the plugin is stable. Can we use the plugin on Windows? Unfortunayely no. Valgrind is stricly linked to the memory management on GNU/Linux and can t run on Windows. 8 Links Redmine containing many information of the project : http://redmine.sbrk.org/projects/kvalgrind Official redmine on KDE.org : https://projects.kde.org/projects/playground/devtools/plugins/kdev-valgrind Wiki of the project : http://redmine.sbrk.org/projects/kvalgrind/wiki Bug tracker : http://redmine.sbrk.org/projects/kvalgrind/issues Gantt : http://redmine.sbrk.org/projects/kvalgrind/issues/gantt 9 Conclusion Even if this project is for C/C++ developers with some knowledge, the integration of a complicated tool at first sight (only with command lines) enables more people to enjoy the possibilities offered by Valgrind in a very simple way. The KDev-Valgrind team - December 9, 2011 14