WebAssembly/Compiler: what changed

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

Old	New		Line
1		-	~~# Prerequisites~~
	1	+	# Prerequisites (optional!)
2	2
3		-	~~The linker wasm-ld from the LLVM project. LLVM 11.0 and 12.0.1 are known to work.~~
	3	+	The initial FPC port for WebAssembly required the _wasm-ld_ from the LLVM project. LLVM 11.0 and 12.0.1 are known to work. The latest FPC version contains an internal linker, making this requirement strictly optional. You can skip this part if you want to.
4	4
5	5		## Fedora
6	6
7		-	~~Development was done, using the Fedora packages llvm-11.0.0-1.fc33.x86_64 and lld-11.0.0-1.fc33.x86_64.~~
	7	+	Development was done, using the Fedora packages llvm-11.0.0-1.fc33.x86_64 and lld-11.0.0-1.fc33.x86_64.
8	8
9	9		## Ubuntu
10	10
11		-	~~Tested on Ubuntu 20.04. wasm-ld is part of package lld-12. Install it and set necessary symlinks:~~
12		-
13		-	~~`% sudo apt install lld-12`\~~
14		-	~~`% ln -sf /usr/lib/llvm-12/bin/wasm-ld ~/bin/wasm32-wasi-wasm-ld`\~~
15		-	~~`% ln -sf /usr/lib/llvm-12/bin/wasm-ld ~/bin/wasm32-embedded-wasm-ld`~~
	11	+	Tested on Ubuntu 20.04. _wasm-ld_ is part of package _lld-12_. Install it and set necessary symlinks:
	12	+	```
	13	+	% sudo apt install lld-12
	14	+	% ln -sf /usr/lib/llvm-12/bin/wasm-ld ~/bin/wasm32-wasi-wasm-ld
	15	+	% ln -sf /usr/lib/llvm-12/bin/wasm-ld ~/bin/wasm32-embedded-wasm-ld
	16	+	```
16	17
17		-	~~Note: This assumes you have a \$HOME/bin directory and it is in PATH.~~
	18	+	Note: This assumes you have a $HOME/bin directory and it is in PATH.
18	19
19	20		## macOS
20	21
21	22		### Catalina
22	23
23		-	Tested on macOS Catalina with LLVM 11. For [MacPorts](https://www.macports.org) wasm-ld is part of package llvm-11; upon installation it exists as wasm-ld-mp-11. Install the package and set necessary symlinks:
24		-
25		-	~~`% sudo port install llvm-11`\~~
26		-	~~`% ln -sf /opt/local/bin/wasm-ld-mp-11 ~/bin/wasm32-wasi-wasm-ld`\~~
27		-	~~`% ln -sf /opt/local/bin/wasm-ld-mp-11 ~/bin/wasm32-embedded-wasm-ld`~~
	24	+	Tested on macOS Catalina with LLVM 11. For [MacPorts](<https://www.macports.org>) _wasm-ld_ is part of package _llvm-11_ ; upon installation it exists as _wasm-ld-mp-11_. Install the package and set necessary symlinks:
	25	+	```
	26	+	% sudo port install llvm-11
	27	+	% ln -sf /opt/local/bin/wasm-ld-mp-11 ~/bin/wasm32-wasi-wasm-ld
	28	+	% ln -sf /opt/local/bin/wasm-ld-mp-11 ~/bin/wasm32-embedded-wasm-ld
	29	+	```
28	30
29		-	~~Note: This assumes you have a \$HOME/bin directory and it is in PATH.~~
	31	+	Note: This assumes you have a $HOME/bin directory and it is in PATH.
30	32
31	33		### Monterey
32	34
33		-	~~Tested on macOS Monterey 12.5.1: wasm-ld is part of the official clang release for macOS: <https://releases.llvm.org/download.html#11.1.0>~~
	35	+	Tested on macOS Monterey 12.5.1 : wasm-ld is part of the official clang release for macOS: <https://releases.llvm.org/download.html#11.1.0>
34	36
35		-	~~Unpack it. When running wasm-ld, macOS might warn, that ldd cannot be verified. Open the System Preferences / Security / General. There should be ldd, unlock, then click Open Anyway.~~
	37	+	Unpack it. When running wasm-ld, macOS might warn, that ldd cannot be verified. Open the System Preferences / Security / General. There should be ldd, unlock, then click Open Anyway.
36	38
37	39		## Windows 10
38	40
39		-	Tested on Windows 10 Home 21H2. Download the [LLVM 12.0.1](https://github.com/llvm/llvm-project/releases/tag/llvmorg-12.0.1) 64-bit Windows installer. You are encouraged to verify the GPG signature on the installer. As administrator, run the installer. Let's say you installed into C:\llvm. Enable Windows 'developer mode' if you have not done so. Then set necessary symlinks:
40		-
41		-	~~` C:\> cd llvm\bin`\~~
42		-	~~` C:\llvm\bin> mklink wasm32-wasi-wasm-ld.exe wasm-ld.exe`\~~
43		-	~~` C:\llvm\bin> mklink wasm32-embedded-wasm-ld.exe wasm-ld.exe`~~
	41	+	Tested on Windows 10 Home 21H2. Download the [LLVM 12.0.1](<https://github.com/llvm/llvm-project/releases/tag/llvmorg-12.0.1>) 64-bit Windows installer. You are encouraged to verify the GPG signature on the installer. As administrator, run the installer. Let's say you installed into C:\llvm. Enable Windows 'developer mode' if you have not done so. Then set necessary symlinks:
	42	+	```
	43	+	C:\> cd llvm\bin
	44	+	C:\llvm\bin> mklink wasm32-wasi-wasm-ld.exe wasm-ld.exe
	45	+	C:\llvm\bin> mklink wasm32-embedded-wasm-ld.exe wasm-ld.exe
	46	+	```
44	47
45		-	~~Add C:\llvm\bin to your PATH.~~
	48	+	Add C:\llvm\bin to your PATH.
46	49
47	50		# Obtaining the compiler sources
48	51
49	52		## Linux and macOS
50	53
51		-	~~The WebAssembly compiler target is part of the 'main' branch of the GitLab FPC source repo. Get the source:~~
52		-
53		-	~~`% git clone `[`https://gitlab.com/freepascal.org/fpc/source.git`](https://gitlab.com/freepascal.org/fpc/source.git)` fpc`~~
54		-
55		-	~~Enter the sources directory:~~
	54	+	The WebAssembly compiler target is part of the 'main' branch of the GitLab FPC source repo. Get the source:
	55	+	```
	56	+	% git clone <https://gitlab.com/freepascal.org/fpc/source.git> fpc
	57	+	```
56	58
57		-	~~`% cd fpc`~~
	59	+	Enter the sources directory:
	60	+	```
	61	+	% cd fpc
	62	+	```
58	63
59	64		## Windows
60	65
61		-	~~The WebAssembly compiler target is part of the 'main' branch of the GitLab FPC source repo. Get the source:~~
62		-
63		-	~~`C:\Users\OnlyMe> git clone `[`https://gitlab.com/freepascal.org/fpc/source.git`](https://gitlab.com/freepascal.org/fpc/source.git)` fpc`~~
64		-
65		-	~~Enter the sources directory:~~
	66	+	The WebAssembly compiler target is part of the 'main' branch of the GitLab FPC source repo. Get the source:
	67	+	```
	68	+	C:\Users\OnlyMe> git clone <https://gitlab.com/freepascal.org/fpc/source.git> fpc
	69	+	```
66	70
67		-	~~`C:\Users\OnlyMe> cd fpc`~~
	71	+	Enter the sources directory:
	72	+	```
	73	+	C:\Users\OnlyMe> cd fpc
	74	+	```
68	75
69	76		# Building and installing
70	77
71		-	~~If you are new to building the compiler, see [[Installing the Free Pascal Compiler]] and [[Cross compiling]].~~
	78	+	If you are new to building the compiler, see [[Installing the Free Pascal Compiler]] and [[Cross compiling]].
72	79
73		-	~~FPC supports two WebAssembly compilation targets: WASI and embedded.~~
	80	+	FPC supports two WebAssembly compilation targets: WASI and embedded.
74	81
75		-	~~## Compilation target: WASI~~
	82	+	## Compilation target: WASIp1
76	83
	84	+	This target supports the WebAssembly System Interface Preview 1 (WASI 0.1).
	85	+
77	86		### Linux and macOS
78	87
79		-	~~Build the compiler and FPC units for the WASI target:~~
	88	+	Build the compiler and FPC units for the WASIp1 target:
	89	+	```
	90	+	% make clean all OS_TARGET=wasip1 CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc
	91	+	```
80	92
81		-	~~`% make clean all OS_TARGET=wasi CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc`~~
	93	+	Then, install, using INSTALL_PREFIX to specify a destination within your home directory:
	94	+	```
	95	+	% make crossinstall OS_TARGET=wasip1 CPU_TARGET=wasm32 INSTALL_PREFIX=$HOME/fpcwasm
	96	+	```
82	97
83		-	~~Then, install, using INSTALL_PREFIX to specify a destination within your home directory:~~
	98	+	Note: On macOS you might have to add _-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk_ to _OPT_.
84	99
85		-	~~`% make crossinstall OS_TARGET=wasi CPU_TARGET=wasm32 INSTALL_PREFIX=$HOME/fpcwasm`~~
	100	+	Make a link to the cross compiler executable _ppcrosswasm32_ :
	101	+	```
	102	+	% ln -sf ~/fpcwasm/lib/fpc/3.3.1/ppcrosswasm32 ~/bin/ppcrosswasm32
	103	+	```
86	104
87		-	~~Note: On macOS you might have to add -XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk to OPT.~~
	105	+	Note: This assumes you have a $HOME/bin directory and it is in PATH.
88	106
89		-	~~Make a link to the cross compiler executable ppcrosswasm32:~~
	107	+	### Windows
90	108
91		-	~~`% ln -sf ~/fpcwasm/lib/fpc/3.3.1/ppcrosswasm32 ~/bin/ppcrosswasm32`~~
	109	+	Make sure the Windows native compiler fpc.exe and the FPC-bundled make.exe are in your PATH. Especially ensure that the FPC make.exe comes first in your PATH; using another make.exe (such as the one installed by Delphi) that happens to be ahead in PATH may not work.
92	110
93		-	~~Note: This assumes you have a \$HOME/bin directory and it is in PATH.~~
	111	+	Build the compiler and FPC units for the WASIp1 target:
	112	+	```
	113	+	C:\Users\OnlyMe\fpc> make clean all OS_TARGET=wasip1 CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc
	114	+	```
94	115
95		-	~~### Windows~~
	116	+	Then, install, using INSTALL_PREFIX to specify a destination folder:
	117	+	```
	118	+	C:\Users\OnlyMe\fpc> make crossinstall OS_TARGET=wasip1 CPU_TARGET=wasm32 INSTALL_PREFIX=c:\fpcwasm PP=fpc
	119	+	```
96	120
97		-	Make sure the Windows native compiler fpc.exe and the FPC-bundled make.exe are in your PATH. Especially ensure that the FPC make.exe comes first in your PATH; using another make.exe (such as the one installed by Delphi) that happens to be ahead in PATH may not work.
	121	+	Add C:\fpcwasm\bin\x86_64-win64 to your PATH to easily run the compiler _ppcrosswasm32.exe_.
98	122
99		-	~~Build the compiler and FPC units for the WASI target:~~
	123	+	## Compilation target: WASIp1threads
100	124
101		-	~~`C:\Users\OnlyMe\fpc> make clean all OS_TARGET=wasi CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc`~~
	125	+	This target supports the WebAssembly System Interface Preview 1 (WASI 0.1) with the [wasi-threads](<https://github.com/WebAssembly/wasi-threads>) proposal.
102	126
103		-	~~Then, install, using INSTALL_PREFIX to specify a destination folder:~~
	127	+	Building the compiler is the same, as described in the previous section, except that _OS_TARGET=_wasip1 needs to be replaced with _OS_TARGET=_wasip1threads.
104	128
105		-	~~`C:\Users\OnlyMe\fpc> make crossinstall OS_TARGET=wasi CPU_TARGET=wasm32 INSTALL_PREFIX=c:\fpcwasm PP=fpc`~~
	129	+	To build programs for this platform, add the
	130	+	```
	131	+	-Twasip1threads
	132	+	```
106	133
107		-	~~Add C:\fpcwasm\bin\x86_64-win64 to your PATH to easily run the compiler ppcrosswasm32.exe.~~
	134	+	compiler option, otherwise it will target wasip1 by default.
108	135
109	136		## Compilation target: Embedded
110	137
111	138		### Linux and macOS
112	139
113		-	~~Build the compiler and FPC units for the 'embedded' target:~~
114		-
115		-	~~`% make clean all OS_TARGET=embedded CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc`~~
116		-
117		-	~~Then, install, using INSTALL_PREFIX to specify a destination within your home directory:~~
118		-
119		-	~~`% make crossinstall OS_TARGET=embedded CPU_TARGET=wasm32 INSTALL_PREFIX=$HOME/fpcwasm`~~
	140	+	Build the compiler and FPC units for the 'embedded' target:
	141	+	```
	142	+	% make clean all OS_TARGET=embedded CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc
	143	+	```
120	144
121		-	~~If you have not built and installed the WASI cross compiler, then make a link to the cross compiler executable ppcrosswasm32;~~
	145	+	Then, install, using INSTALL_PREFIX to specify a destination within your home directory:
	146	+	```
	147	+	% make crossinstall OS_TARGET=embedded CPU_TARGET=wasm32 INSTALL_PREFIX=$HOME/fpcwasm
	148	+	```
122	149
123		-	~~`% ln -sf ~/fpcwasm/lib/fpc/3.3.1/ppcrosswasm32 ~/bin/ppcrosswasm32`~~
	150	+	If you have not built and installed the WASI cross compiler, then make a link to the cross compiler executable _ppcrosswasm32_ ;
	151	+	```
	152	+	% ln -sf ~/fpcwasm/lib/fpc/3.3.1/ppcrosswasm32 ~/bin/ppcrosswasm32
	153	+	```
124	154
125		-	~~Note: This assumes you have a \$HOME/bin directory and it is in PATH.~~
	155	+	Note: This assumes you have a $HOME/bin directory and it is in PATH.
126	156
127	157		### Windows
128	158
129		-	Make sure the Windows native compiler fpc.exe and the FPC-bundled make.exe are in your PATH. Especially ensure that the FPC make.exe comes first in your PATH; using another make.exe (such as the one installed by Delphi) that happens to be ahead in PATH may not work.
130		-
131		-	~~Build the compiler and FPC units for the 'embedded' target:~~
132		-
133		-	~~`C:\Users\OnlyMe\fpc> make clean all OS_TARGET=embedded CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc`~~
	159	+	Make sure the Windows native compiler fpc.exe and the FPC-bundled make.exe are in your PATH. Especially ensure that the FPC make.exe comes first in your PATH; using another make.exe (such as the one installed by Delphi) that happens to be ahead in PATH may not work.
134	160
135		-	~~Then, install, using INSTALL_PREFIX to specify a destination folder:~~
	161	+	Build the compiler and FPC units for the 'embedded' target:
	162	+	```
	163	+	C:\Users\OnlyMe\fpc> make clean all OS_TARGET=embedded CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc
	164	+	```
136	165
137		-	~~`C:\Users\OnlyMe\fpc> make crossinstall OS_TARGET=embedded CPU_TARGET=wasm32 INSTALL_PREFIX=c:\fpcwasm PP=fpc`~~
	166	+	Then, install, using INSTALL_PREFIX to specify a destination folder:
	167	+	```
	168	+	C:\Users\OnlyMe\fpc> make crossinstall OS_TARGET=embedded CPU_TARGET=wasm32 INSTALL_PREFIX=c:\fpcwasm PP=fpc
	169	+	```
138	170
139		-	~~Add C:\fpcwasm\bin\x86_64-win64 to your PATH if you have not already done so.~~
	171	+	Add C:\fpcwasm\bin\x86_64-win64 to your PATH if you have not already done so.
140	172
141	173		# Using the compiler
142	174
143		-	For Linux and macOS, if you have installed the cross compiler and units into \$HOME/fpcwasm (as per the commands used above), then you need to configure \$HOME/.fpc.cfg so that the cross compiler can locate its units.
144		-
145		-	~~For Ubuntu, add these lines:~~
	175	+	For Linux and macOS, if you have installed the cross compiler and units into $HOME/fpcwasm (as per the commands used above), then you need to configure $HOME/.fpc.cfg so that the cross compiler can locate its units.
146	176
147		-	~~#ifdef cpuwasm32~~
	177	+	For Ubuntu, add these lines:
	178	+	```
	179	+	#ifdef cpuwasm32
148	180		-Fu/home/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/*
149	181		-Fu/home/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/rtl
150	182		#endif
151		-
152		-	~~For macOS, add these lines:~~
	183	+	```
153	184
154		-	~~#ifdef cpuwasm32~~
	185	+	For macOS, add these lines:
	186	+	```
	187	+	#ifdef cpuwasm32
155	188		-Fu/Users/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/*
156	189		-Fu/Users/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/rtl
157	190		#endif
	191	+	```
158	192
159		-	~~On Windows, if you have set C:\fpcwasm\bin\x86_64-win64 directory in your PATH, then ppcrosswasm32.exe will be able to find its units.~~
	193	+	On Windows, if you have set C:\fpcwasm\bin\x86_64-win64 directory in your PATH, then _ppcrosswasm32.exe_ will be able to find its units.
160	194
161	195		# Using the compiler with Lazarus
162	196
163		-	~~When you create a new Lazarus project for a wasm program you can use the Simple Program template and then adjust the Project / Project Options / Compiler Options:~~
	197	+	When you create a new Lazarus project for a wasm program you can use the _Simple Program_ template and then adjust the _Project / Project Options / Compiler Options_ :
164	198
165		-	- Paths / Target file name: Lazarus 2.3.0 (Dec 28th 2021) appends the required .wasm file extension to the output file. To support older IDEs disable Apply conventions and set \<programname\>.wasm.
166		-	~~- Config and Target / Target platform:~~
167		-	~~- Target OS: Wasi~~
168		-	~~- Target CPU: wasm32~~
169		-	~~- Debugging / Generate info for debugger: disable (Dec 28th 2021: otherwise you will get can't find unit linfodwrf)~~
170		-	~~- Compiler Commands / Compiler / Command: If you are using different fpc versions / folders you can here set the path to ppcrosswasm32 (e.g. Linux: /usr/lib/fpc/3.3.1/ppcrosswasm32)~~
	199	+	* Paths / Target file name: Lazarus 2.3.0 (Dec 28th 2021) appends the required .wasm file extension to the output file. To support older IDEs disable _Apply conventions_ and set _< programname>.wasm_.
	200	+	* Config and Target / Target platform:
	201	+	* Target OS: Wasi
	202	+	* Target CPU: wasm32
	203	+	* Debugging / Generate info for debugger: disable (Dec 28th 2021: otherwise you will get can't find unit linfodwrf)
	204	+	* Compiler Commands / Compiler / Command: If you are using different fpc versions / folders you can here set the path to ppcrosswasm32 (e.g. Linux: /usr/lib/fpc/3.3.1/ppcrosswasm32)
171	205
172	206		# See Also
173	207
174		-	~~- [[WebAssembly]]~~
	208	+	* [[WebAssembly]]
175	209
176	210		---
177		-	From the Free Pascal wiki, page "WebAssembly/Compiler", as it stood on 2022-09-08 after a change by Trev, 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).
178		-	~~Category: WebAssembly~~
	211	+	From the Free Pascal wiki, page "WebAssembly/Compiler", as the Internet Archive kept it on 2026-09-26, last changed on 2025-02-28. 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