Remote Debugging: what changed

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

Old	New		Line
1	1		## Introduction
2	2
3	3		Remote debugging means you work on your local computer and you want to start and debug a program on another computer, the remote machine. In the following examples the name of the local computer is 'localcomp' and the name of the remote computer is 'remotecomp'.
4	4
5	5		> Note: Remote debugging will only work if the gdb supports async mode (see gdb doc for "set target async"). GDBServer usually does. GDB does for some targets only.
6	6		>
7	7		> In some cases gdb/gdbserver does support it, but not if "mi" mode is used (used by the IDE. A workaround for this must yet be implemented in the IDE.\
8	8		> IF async mode is not supported, or not for "mi" then:
9	9		>
10	10		> - It is currently not possible to use the "Pause" function to interrupt the running application.
11	11		> - It is not possible to modify break-/watch-points, while the application in the debugger is running.
12	12		> - One should no switch editor tabs, or open/close units, while the application in the debugger is running.
13	13		>
14	14		> The 2nd and 3rd can be done, if the app in the debugger is paused. The only way for the app to become paused is by reaching a breakpoint that was set before the app was run.
15	15
16	16		## Using SSH (Secure Shell)
17	17
18	18		SSH (SSH client) is a program for logging into a remote machine and for executing commands on a remote machine. It provides secure encrypted communications between two untrusted hosts over an insecure network. X11 connections and arbitrary TCP/IP ports can also be forwarded over the secure channel.
19	19
20	20		See the SSH man page for details. This text only covers SSH protocol 2. For differences for protocol 1 see the SSH man page.
21	21
22	22		### Requirements for Lazarus
23	23
24	24		You must be able to log in via ssh to the remote machine (the computer where the program will run). This means the remote machine has an installed and running SSH server and you have an account allowed to login from your local machine (the computer where the Lazarus IDE is running).
25	25
26	26		You can test this by doing:
27	27
28	28		``` bash
29	29
30	30		ssh username@remotecomp ls -la
31	31		```
32	32
33	33		This will create an SSH connection to 'remotecomp' with the username 'username'. After authentication it will print out a directory listing and return.
34	34
35	35		#### Configuring SSH
36	36
37	37		The IDE needs an SSH connection that does not prompt for a password. There are a lot of possibilities to achieve this. This text only describes a few. For security reasons it is strongly recommended that you read the SSH manpage.
38	38
39	39		Solution 1: User based authentication.
40	40
41	41		This will allow one specific user on the local computer to establish an SSH connection to the remote computer as a specific user without prompting for passwords.
42	42
43	43
44	44		ToDo: describe the server settings. On redhat this works without any change.
45	45
46	46		Step 1
47	47		create the public and private keys on the local machine
48	48
49	49		This will create two files on the local machine:
50	50
51		-	~~` ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub`~~
	51	+	```text
	52	+	~/.ssh/id_rsa and ~/.ssh/id_rsa.pub
	53	+	```
52	54
53	55		If you already have these files, skip this step.
54	56
55	57		``` bash
56	58
57	59		ssh-keygen -t rsa
58	60		```
59	61
60	62		Keep the default and leave the passphrase empty.
61	63
62	64		Step 2
63	65		copy the public key of the local machine to the remote machine
64	66
65	67		``` bash
66	68
67	69		scp ~/.ssh/id_rsa.pub user@remotecomp:remote.pub
68	70		```
69	71
70	72		Step 3
71	73		create the file ~/.ssh/authorized_keys2 on the remote machine
72	74
73	75		``` bash
74	76
75	77		ssh user@remotecomp
76	78		touch ~/.ssh/authorized_keys2
77	79		chmod 600 ~/.ssh/authorized_keys2
78	80		```
79	81
80	82		The chmod will set the permissions to only allow yourself to read the file. SSH requires this.
81	83
82	84		``` bash
83	85
84	86		cat remote.pub >> ~/.ssh/authorized_keys2
85	87		rm remote.pub
86	88		exit
87	89		```
88	90
89	91		Step 4
90	92		test
91	93
92	94		You should now be able to login without password.
93	95
94	96		``` bash
95	97
96	98		ssh user@remotecomp
97	99		```
98	100
99	101		Step 5
100	102		Setup the ssh debugger in the IDE
101	103
102	104		ToDo
103	105
104	106		------------------------------------------------------------------------
105	107
106	108		Step 6
107	109		Set "Run parameters"
108	110
109	111		For remote debug we need to set the correct value for "Host application", "Command line parameters" and "Working directory". Remember: It is remote!
110	112
111	113		![](/wiki-images/1/18/Remote_debug_run_parameters.png)
112	114
113	115		Step 7
114	116		Set "Debugger parameters"
115	117
116	118		Select "Debugger type and path" to "GNU Debugger trough SSH(ssh)"
117	119
118	120		![](/wiki-images/7/7f/Remote_debug_debuger_parameters.png) ToDo
119	121
120	122		## Using gdbserver
121	123
122	124		For now this is the best approach I could find: Steps for remote debugging from Windows to Linux machine, other situations should not be so much different:
123	125
124	126		1- Manually include gdbmidebugger the public "uses" clause of debugmanager.pas file located in lazarus/ide and recompile ide.
125	127
126	128		2- Install gdb and gdbserver on Linux.
127	129
128	130		3- Make a cross compile Lazarus.
129	131
130	132		4- Set IDE options/Debugger to gdbserver and in the debugger options on the bottom set Debugger_Remote_Hostname to remote Linux machine IP or name and set the port to 2159.
131	133
132	134		5- Add a Linux build mode to project option.
133	135
134	136		6- Build project on Linux build mode.
135	137
136	138		7- Use whatever tool like WinSCP to move binary file to Linux machine. for WinSCP use it like this : WinSCP.com /script=script.txt and content of script.txt will be like this (you can use WinSCP 5.8 and later session/ script menu to make and modify it) :
137	139
138	140		``` pascal
139	141		open sftp://username:remotepassword@remotenameorip/ -hostkey="XXXXXX"
140	142
141	143		cd ./projectdir
142	144		put -permissions=744 "C:\Project\project1"
143	145
144	146		exit
145	147		```
146	148
147	149		8- Run gdbserver on remote machine like this : gdbserver host:2159 ./project1
148	150
149	151		9- Set breakpoints where you want.
150	152
151	153		10- Run project in your IDE and test it.
152	154
153	155		For more reading see :
154	156
155	157		- [[http://forum.lazarus.freepascal.org/index.php/topic,32393.0.html Remote debugging from Windows to Linux]]
156	158		- [[http://forum.lazarus.freepascal.org/index.php/topic,19014.msg107930.html\|http://forum.lazarus.freepascal.org/index.php/topic,19014.msg107930.html#msg107930 Initial GdbServer post on forum]]
157	159		- [[http://forum.lazarus.freepascal.org/index.php/topic,20101.msg115408.html\|http://forum.lazarus.freepascal.org/index.php/topic,20101.msg115408.html#msg115408 target async support (ssh and gdbserver)]]
158	160		- [[https://forum.lazarus.freepascal.org/index.php/topic,66960.msg514304.html\|https://forum.lazarus.freepascal.org/index.php/topic,66960.msg514304.html#msg514304 Some of the gdb-server backend settings explained]]
159	161
160	162		## Using gdbserver on cross-platform remote
161	163
162	164		When, say, you want cross-build an application for Raspberry Pi on Windows and then debug it remotely on RasPi, the default gdb.exe wouldn't work. You need to obtain gdb-multiarch (supports different remote architectures). For Windows, the easiest way is to install [MSYS2 distribution](https://www.msys2.org) and then install the package gdb-multiarch ([w64 gdb-multiarch](https://packages.msys2.org/package/mingw-w64-x86_64-gdb-multiarch)).
163	165
164	166		Then, in Lazarus, in Debugger backend options, select "GNU remote debugger (gdbserver)", set "Debugger path" to gdb-multiarch.exe, and specify "Architecture" arm.
165	167
166	168		## Using avr-gdb
167	169
168	170		I've managed to debug AVR programs using two different methods:
169	171
170	172		Executing code through [simavr](https://github.com/buserror/simavr) (an AVR simulator)
171	173
172	174		simavr includes a gdbserver interface. To simulate and debug code, launch simavr with the -g option:
173	175
174		-	~~`./runavr -g -m atmega328p -f 16000000 <firmware>`~~
	176	+	```text
	177	+	./runavr -g -m atmega328p -f 16000000 <firmware>
	178	+	```
175	179
176	180		By default a remote gdb connection is available on port 1234.
177	181
178	182		Running on hardware and debugging over DEBUGwire using [dwire-debug](https://github.com/dcwbrown/dwire-debug)
179	183
180	184		Launch dwire as follows:
181	185
182		-	~~`./dwdebug device <serial port>, gdbserver, qr`~~
	186	+	```text
	187	+	./dwdebug device <serial port>, gdbserver, qr
	188	+	```
183	189
184	190		By default a remote gdb connection is available on port 4444. The qr option will result in dwire exiting with the target running when the debug connection is killed. Note that currently dwire returns S00 when hitting a breakpoint. This results in Lazarus displaying a popup dialog with an error message. This is to indicate that a non-standard signal was received and is merely an annoyance. See [this](https://github.com/dcwbrown/dwire-debug/issues/33) for a fix.
185	191
186	192		To configure Lazarus for debugging over avr-gdb
187	193
188	194		- Select GNU remote debugger under Debugger options
189	195		- Enter path to avr-gdb
190	196		- Enter the appropriate port number
191	197		- At the moment a Lazarus [patch](https://bugs.freepascal.org/view.php?id=32084) is required because no process ID is available on the embedded platform.
192	198
193	199		I've tested different versions of gdb compiled for AVR target:
194	200
195	201		- gdb 6.6 - Doesn't work because async mode isn't supported.
196	202		- gdb 7.0.1 - ~~Works~~ Sometimes work, see note below.
197	203		- gdb 8.0-9.1 - Doesn't work as is, but work with this [patch](https://sourceware.org/bugzilla/show_bug.cgi?id=13519#c13).
198	204		- gdb 10.1 - This version finally includes the patch to fix the disassemble bug.
199	205
200	206		Notes
201	207
202	208		- After I upgraded Linux Mint and retested gdb 7.0.1 I noticed the following warning while testing a debug session:
203	209
204	210		`warning: (Internal error: pc 0xa2 in read in psymtab, but not in symtab.)` GDB would sometimes not work properly and debugging from Lazarus using this version of gdb could hang the IDE.
205	211
206	212		- Using gdb 10.1 with Lazarus gdbmi debugger gives an error on startup if the AVR RTL has been compiled with debug information. This error does not appear to affect the stability or functionality of gdb with Lazarus (based on preliminary testing).
207	213
208	214		---
209	215		From the Free Pascal wiki, page "Remote Debugging", as it stood on 2024-04-13 after a change by Martin, 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