Debugging with Valgrind: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Introduction
2	2
3	3		Valgrind is system for debugging and profiling Linux programs. It comprises of the Valgrind framework and set of tools that can automatically detect many memory management and threading bugs, and profile your programs in detail. You can read about Valgrind here <https://valgrind.org/>
4	4
5	5		A program running under Valgrind is not executed directly by the CPU. Instead it runs on a synthetic CPU provided by Valgrind. This allows Valgrind to have full control and track program and resources very meticulously.
6	6
7	7		Valgrind can be used as standalone issue reporting or performance profiling tool. Also it can be used as a debugger. For this it includes VGDB utility that is GDB-compatible interface to Valgrind.
8	8
9	9		The debugging applications stack is following:
10	10
11	11		- GDB
12	12		- VGDB
13	13		- Valgrind executing YourProgram
14	14
15	15		Though GDB can connect to VGDB directly (via interprocess communication), Lazarus cannot use this mode. You have to use Remote debugging over TCP. In this setup VGDB plays role of GDBServer listening on a TCP port, and Lazarus via GDB connects to it.
16	16
17	17		So the debugging applications stack with Lazarus will be:
18	18
19	19		- Lazarus IDE
20	20		- GDB
21	21		- tcp/ip
22	22		- VGDB
23	23		- Valgrind executing YourProgram
24	24
25	25		Usually you will run all parts on same computer. But there is possibility to run them on 2 computers via network.
26	26
27	27		In the following example everything will be on same computer. Network interface will be localhost and TCP port will be 33333.
28	28
29	29		## Configuration
30	30
31	31		### Install valgrind in your system
32	32
33	33		Refer to Valgrind resources to install it.
34	34
35	35		### Compile your program
36	36
37	37		(here it is named valgrind_test1.pas) with Valgrind option (-gv). Select menu Project -\> Project Options
38	38
39		-	~~<figure>~~
40	39		<img src="valgrind_project_options.png" title="valgrind_project_options.png" width="600" />
41		-	~~<figcaption>valgrind_project_options.png</figcaption>~~
42		-	~~</figure>~~
43	40
44	41		### Configure Lazarus debugger.
45	42
46	43		Select menu Tools -\> Options
47	44
48		-	~~<figure>~~
49	45		<img src="valgrind_tools_options.png" title="valgrind_tools_options.png" width="600" />
50		-	~~<figcaption>valgrind_tools_options.png</figcaption>~~
51		-	~~</figure>~~
52	46
53	47		## Debugging
54	48
55	49		### Start Valgrind and VGDB in a separate shell
56	50
57	51		```shell
58	52		valgrind --tool=memcheck --leak-check=yes --log-file=valgrind.trc --vgdb-error=0 ./valgrind_test1 &
59	53		sleep 2; vgdb --port=33333
60	54		```
61	55
62	56		### Run your program in Lazarus and debug it
63	57
64	58		Actually the program is already run by Valgrind, it is just staying in debugger and waiting for continue.
65	59
66	60		Please note Valgrind is accurate but it is not a fastest debugger. Execution will be much slower than usual. Be patient.
67	61
68	62		Lazarus via VGDB communicates with the program in Valgrind. You can set breakpoints, inspect variable values and so on, like in regular debugger.
69	63
70	64		Lasarus will stop on lines where Valgrind throws exceptions. Valgrind tracks memory usage very carefully and detects the issues where FPC, RTL and a Memory Manager may ignore memory misuse. Like in example below, at line 4.
71	65
72	66		``` pascal
73	67		mo:=TMyObj.Create;
74	68		mo.Field:=12345;
75	69		mo.Free;
76	70		if mo.Field = 0 // Mistakenly accessing released memory block
77	71		then exit;
78	72		```
79	73
80	74		Lazarus will show a message when Valgrind issues an exception.
81	75
82		-	~~<figure>~~
83	76		<img src="valgrind_error.png" title="valgrind_error.png" width="400" />
84		-	~~<figcaption>valgrind_error.png</figcaption>~~
85		-	~~</figure>~~
86	77
87	78		After you close it Lazasarus will position you on a source row where the exception has happened.
88	79
89	80		Lazarus tells you pretty much nothing about what actually happened. Valgrind will give you lots of details. To get these details you can either take a look into Valgrind trace file itself. But more convenient is to load the trace file into IDE. Select menu View -\> Leaks and Traces Open valgrind.trc
90	81
91		-	~~<figure>~~
92	82		<img src="valgrind_trace.png" title="valgrind_trace.png" width="800" />
93		-	~~<figcaption>valgrind_trace.png</figcaption>~~
94		-	~~</figure>~~
95	83
96	84		Here you can see the errors descriptions and three call stacks for each error: for the place where the exception happened, where the memory was freed and where it was allocated. All this is especially helpful for bug fixing. Select a line, double click and Lazarus will open a file and position cursor at a line in question.
97	85
98	86		## Other suggestions
99	87
100	88		Sometimes it can be still unclear if some memory misuse or a leak happened inside RTL or OS binaries. You can compile RTL with debugging info for Valgrind and without optimization. Please refer to FPC Wiki how to rebuild RTL.
101	89
102	90		In some cases Valgrind can generate so called false positives. For example, a small variable was allocated in stack.
103	91
104	92		``` pascal
105	93		var A2: array[2] of char;
106	94		```
107	95
108	96		Then the variable was populated from a file and then compared to a constant
109	97
110	98		``` pascal
111	99		if A2 = 'AA' then ...
112	100		```
113	101
114	102		FPC may choose to use MMX instructions for the comparison and allocates 16 bytes block for it, populating just first 2 bytes from the variable. Valgrind may detect it as an error of reading from uninitialized block. Technically it is correct - only two bytes were initialized, and the rest 14 bytes of the alignment block were not initialized but still scanned by MMX instruction. FPC is aware of this, it will mask the result and never use the result of the scan from masked bytes. But Valgrind still treats this as an error. As soon as bytes were allocated and scanned - it is access to uninitialized memory block.
115	103
116	104		You can suppress reporting for such logical false positives and for other issues in OS or 3-rd party binaries like GTK, X11, etc, to concentrate more on your code. Please refer to Valgrind documentation regarding suppressions.
117	105
118	106		## See also
119	107
120	108		- [[GDB Debugger Tips\|General tips/info on debugging]]
121	109
122	110		---
123	111		From the Free Pascal wiki, page "Debugging with Valgrind", as it stood on 2020-03-06 after a change by Mm7, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history