Lazarus and Free Pascal on WSL2: what changed

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

Old	New		Line
1	1		## Can a Linux FPC-generated 'hello world' be run unmodified on WSL-2 ?
2	2
3	3		Yes
4	4		linux FPC-generated 'hello world' can run unmodified on WSL-2.
5	5
6	6		More complex applications can run (i.e. FPC itself installed from a repository)
7	7
8	8		## Can the Linux version of FPC be installed and run unmodified on WSL2 ?
9	9
10	10		In particular: the program and compiler issue direct kernel calls.
11	11
12	12		We need to know if this is working, or if a LIBC linked version of the Linux binaries is needed.
13	13
14	14		Yes
15	15		The easiest way is to install through the repository.
16	16
17	17		Direct Kernel calls work fine under WSL2.
18	18
19	19		## Can a Windows executable execute a WSL2 program, in particular, the compiler.
20	20
21	21		If yes, this must be demonstrated this using a Win32 FPC program.
22	22
23	23		If not, document what the problems are.
24	24
25	25		Yes (potential problems)
26	26		There's [wslwrap](https://github.com/skalogryz/wslwrap) (Win32 FPC program) application provided that's executing WSL2 program.
27	27
28	28
29	29		There's an outstanding issue with truncating and output buffer, if pipe redirection is used:
30	30
31	31
32	32		<https://github.com/microsoft/WSL/issues/4082>
33	33
34	34		<https://github.com/microsoft/WSL/issues/4184>
35	35
36	36		This limits the application of WSL application, due to possible characters missing in the output.
37	37
38	38		## Can the Lazarus IDE execute the WSL2 Linux compiler ?
39	39
40	40		Yes
41	41		The only tested approach is a quick substitute of the compiler executable, that runs WSL2 linux compiler.
42	42
43	43		One of the approaches is described at: <https://wiki.freepascal.org/Windows_Subsystem_for_Linux#Quick_and_Dirty_-_Using_WSL_FPC_from_Windows>
44	44
45	45		Another approach using the latest wslwrap version is to replace fpc.exe (make a backup!) with wslwrap.exe (copying over) and creating fpc.wrp file with
46	46
47	47
48	48		exe=fpc
49	49
50	50		This will allow to compile -TLinux projects, BUT it's also causing interference in IDE itself, as IDE components (i.e. Codetools) depends on the "windows" version of FPC used.
51	51
52	52		Windows vs Linux paths are creating conflicts when using WSL compiler. Examples are of such conflicts are (The project was configured to use a wsl-wrapped FPC):
53	53
54	54		`Warning: [TPCTargetConfigCache.Update] cannot find real compiler for this platform: Compiler="C:\FPC_Laz\wsltools\fpc.exe" Options="-FrC:\lazarus\components\codetools\fpc.errore.msg" RealCompiler="C:\Users\Owner\AppData\Local\lazarus\/usr/lib/fpc/3.0.0/ppcx64"`\
55		-	\
	55	+
56	56		`Hint: [TPCTargetConfigCache.NeedsUpdate] TargetOS="linux" TargetCPU="x86_64" Options="" real compiler file changed "C:\Users\Owner\AppData\Local\lazarus\/usr/lib/fpc/3.0.0/ppcx64"`\
57		-	\
	57	+
58	58		`Warning: [TPCTargetConfigCache.Update] fpc.exe found cfg a file, the IDE did not: "C:\Users\Owner\AppData\Local\lazarus\\etc\fpc.cfg"`
59	59
60	60
61	61		Note: a custom compiler can be specified per project (+per build mode?), rather than the entire environment .
62	62
63	63		## Can a Windows executable execute & debug a WSL2 program using WSL2 gdb ?
64	64
65	65		(This is assuming that a WSL2 version of gdb exists. If not, document this.).
66	66
67	67		In particular, can Lazarus use the WSL2 gdb if such exists.
68	68
69	69		Practically - No (Potentially- Yes)
70	70		Gdb does present in WSL2 and needs to be installed additionally
71	71
72	72		While it's possible to run WSL2 gdb (and it's surely possible to configure Lazarus to install Gdb)
73	73
74	74		Due to glitches with WSL2 pipe redirection, it's not possible to get gdb reports on time (whenever gdb stops on break point or an error). Lazarus IDE is unable detect the change in the execution.
75	75
76	76		### Setting up a project
77	77
78	78
79	79		1\. Copy wslwrap.exe twice. One for fpc.exe and another for gdb.exe.
80	80
81	81		2\. Create corresponding .wrp file
82	82
83	83
84	84		gdb.wrp should look like this:
85	85
86	86		`exe=gdb`\
87	87		`inp.dummy=0`\
88	88		`inp.wintonix=1`\
89	89		`shell=1`
90	90
91	91
92	92
93	93		the debugger doesn't need to have "dummy" input, because a normal commands would be sent by IDE
94	94
95	95		the all paths in the commands needs to be replaced. Lazarus is Win, and it sends Windows Paths, those has to be converted to linux paths (so gdb would seet hem)
96	96
97	97		shell must be used, as Ggb checks for the environment. If it doesn't detect a proper shell it would use "exec" command in order to launch a child process, which would eventually fail.
98	98
99		-	~~<figure>~~
100		-	~~<img src="wsl-setting-up.png" title="wsl-setting-up.png" />~~
101		-	~~<figcaption>wsl-setting-up.png</figcaption>~~
102		-	~~</figure>~~
	99	+	![](/wiki-images/1/1e/Wsl-setting-up.png)
103	100
104	101
105	102		3\. Specify the new compiler executable in the project setting (not to mess up with IDE)
106	103
107		-	~~<figure>~~
108		-	~~<img src="wsl-compiler-proj.png" title="wsl-compiler-proj.png" />~~
109		-	~~<figcaption>wsl-compiler-proj.png</figcaption>~~
110		-	~~</figure>~~
	104	+	![](/wiki-images/f/fc/Wsl-compiler-proj.png)
111	105
112	106
113	107		3.1 You also want to uncheck "Apply conventions" for "Target name" of "Compiler Options/Paths" and update "Target file name" by removing ".exe" extension.
114	108
115		-	~~<figure>~~
116		-	~~<img src="wsl-project-compiler-options.png" title="wsl-project-compiler-options.png" />~~
117		-	~~<figcaption>wsl-project-compiler-options.png</figcaption>~~
118		-	~~</figure>~~
	109	+	![](/wiki-images/4/40/Wsl-project-compiler-options.png)
119	110
120	111		The IDE will start sending a lot of warning regarding non existing configuration files and unsupported targets. Those can be ignored as files would be used by the compiler from WSL and those configuration and files are present in WSL environment.
121	112
122	113
123	114		4\. Specify the wrapped gdb file name in debugger options
124	115
125		-	~~<figure>~~
126		-	~~<img src="wsl-debugger-options.png" title="wsl-debugger-options.png" />~~
127		-	~~<figcaption>wsl-debugger-options.png</figcaption>~~
128		-	~~</figure>~~
	116	+	![](/wiki-images/8/89/Wsl-debugger-options.png)
129	117
130	118
131	119		5\. Run the project.
132	120
133		-	~~<figure>~~
134		-	~~<img src="wsl_debug.png" title="wsl_debug.png" />~~
135		-	~~<figcaption>wsl_debug.png</figcaption>~~
136		-	~~</figure>~~
	121	+	![](/wiki-images/6/6d/Wsl_debug.png)
137	122
138	123		## Can the FPC windows 64-bit compiler cross-compile a -Tlinux program using WSL 2. If yes, how ?
139	124
140	125		Yes (but undesired approach?)
141	126		It's possible to use WSL2 utils as cross-compiler binary utils. For example an executable x86_64-linux-ld.exe can be substituted with call to "wsl ld", the link.res file generated by FPC is still using windows paths. Preventing the linux linker from being able to build a binary.
142	127
143	128		It's possible to update link.res prior to the execution of ld, and convert Windows paths to WSL (Linux) paths.
144	129
145	130		Steps (assumption is made that Win32 FPC doesn't have any cross-compile utils installed):
146	131
147	132
148	133		1\. have WSL2 installed
149	134
150	135		2\. install FPC to WSL2 matching version that is matching the one currently used on Windows. (this is critical as FPC would match units used). (for example the official Lazarus release comes with 3.0.4. Distro's repository would have FPC 3.0.0 available. This won't work for cross-compiling, FPC 3.0.4 needs to be isntalled)
151	136
152	137		2.1 download (in win32) linux-xxx.xxx.tar from the official FPC
153	138
154	139		2.2 unpack tar file
155	140
156	141		2.3 run "wsl sudo ./install.sh" (sudo is need to be able to install to default /usr dir)
157	142
158	143		3\. copy x86_64-linux units from WSL to your windows FPC directory (i.e. C:\lazarus\fpc\3.0.4\units\x86_64-linux). You can do that by running the following in Windows command line
159	144
160	145
161	146
162	147		cd "C:\lazarus\fpc\3.0.4\units"
163	148
164	149		wsl cp -r /usr/lib/fpc/3.0.4/units/x86_64-linux ./
165	150
166	151		4\. Get the latest [wslwrap](https://github.com/skalogryz/wslwrap) project and compile it.
167	152
168	153		4.1 Move wslwrap.exe to C:\lazarus\fpc\3.0.4\bin\x86_64-linux\x86_64-linux-ld.exe (not the destinatino folder might not exit)
169	154
170	155		4.2 create the file C:\lazarus\fpc\3.0.4\bin\x86_64-linux\x86_64-linux-ld.wrp. Add two following lines
171	156
172	157
173	158		exe=ld
174	159
175	160		linkres=1
176	161
177	162		This instructs the current executable when doing call over WSL to cal "ld", but also update link.res file prior to that
178	163
179	164		5\. Done. Try to compile hello world pas using command line:
180	165
181	166
182	167		C:\lazarus\fpc\3.0.4\bin\x86_64-win64\fpc.exe -Tlinux test.pas
183	168
184	169		as a result you should get "test" binary, that can be ran "wsl ./test"
185	170
186	171		The problem is that might require to build more "exceptions" and "wsl" hacks in future. Using straight forward Linux cross-compiler might be more reliable approach - OR - instead using WSL calling directly, rather than as a cross-compiler.
187	172
188	173		Also attempt to use "Math" unit fails immediately due to IE 200208151: <https://bugs.freepascal.org/view.php?id=35781>
189	174
190	175		## Summary
191	176
192	177		- WSL2 still requires its own fixes.
193	178		- a number of changes are required in Lazarus IDE to make it "wsl" aware. (so it would use WSL paths, instead of Windows paths). Without that changes, even a smarter "wslwrap" utility would have its own challenges.
194	179		- no changes are needed in FPC. Though fixing the internal error would make a better use of wsl as cross-compiler.
195	180
196	181		## See Also
197	182
198	183		- [[WSL]]
199	184
200	185		---
201	186		From the Free Pascal wiki, page "Lazarus and Free Pascal on WSL2", as it stood on 2019-07-12 after a change by Skalogryz, 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).
202	187		Category: Linux
203	188		Category: Windows

Back to history