Difference between revisions of "WebAssembly/Compiler"

From Lazarus wiki
Jump to navigationJump to search
(Remove mention of demo which is now linked on main Wasm page)
 
(45 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== Instructions ==
+
= Prerequisites =
=== Compiling the compiler ===
 
  
Get the sources:
+
The linker ''wasm-ld'' from the LLVM project. LLVM 11.0 and 12.0.1 are known to work.
  
git clone https://github.com/skalogryz/freepascal fpc-wasm
+
== Fedora ==
 
switch to correct branch:
 
cd fpc-wasm
 
git checkout webasm
 
  
compile:
+
Development was done, using the Fedora packages llvm-11.0.0-1.fc33.x86_64 and lld-11.0.0-1.fc33.x86_64.
cd compiler
 
 
 
====Using Lazarus====
 
open ppcwasm.lpi
 
hit the "compile" button.
 
  
=====Using command-line=====
+
== Ubuntu ==
fpc -dnoopt -dwasm -Fiwasm -Fuwasm -Fusystems -S2 pp.pas
 
  
the compiler can be renamed
+
Tested on Ubuntu 20.04. ''wasm-ld'' is part of package ''lld-12''. Install it and set necessary symlinks:
  mv pp ppwasm
+
  % sudo apt install lld-12
or, on windows:
+
% ln -sf /usr/lib/llvm-12/bin/wasm-ld ~/bin/wasm32-wasi-wasm-ld
  mv pp.exe ppwasm.exe
+
  % ln -sf /usr/lib/llvm-12/bin/wasm-ld ~/bin/wasm32-embedded-wasm-ld
  
=== Using the compiler ===
+
Note: This assumes you have a $HOME/bin directory and it is in PATH.
  
You need a system.pas unit. It can be found here:
+
== MacOS ==
  
[https://github.com/skalogryz/wasm-demo wasm-demo]
+
Tested on MacOS Catalina with LLVM 11. For [https://www.macports.org MacPorts], ''wasm-ld'' is part of package ''llvm-11''; upon installation it exists as ''wasm-ld-mp-11''. Install the package and set necessary symlinks:
 +
% sudo port install llvm-11
 +
% ln -sf /opt/local/bin/wasm-ld-mp-11 ~/bin/wasm32-wasi-wasm-ld
 +
% ln -sf /opt/local/bin/wasm-ld-mp-11 ~/bin/wasm32-embedded-wasm-ld
  
You'll also need the wasm bin tools:
+
Note: This assumes you have a $HOME/bin directory and it is in PATH.
  
[https://github.com/WebAssembly/wabt/releases wasm bin tools]
+
== Windows 10 ==
  
Extract the binaries and put them somewhere in your PATH.
+
Tested on Windows 10 Home 21H2. Download the [https://github.com/llvm/llvm-project/releases/tag/llvmorg-12.0.1 LLVM 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:
 +
  C:\> cd llvm\bin
 +
  C:\llvm\bin> mklink wasm32-wasi-wasm-ld.exe wasm-ld.exe
 +
  C:\llvm\bin> mklink wasm32-embedded-wasm-ld.exe wasm-ld.exe
  
And you'll need some more wasmtool:
+
Add C:\llvm\bin to your PATH.
  
[https://github.com/skalogryz/wasmbin wasmtool]
+
= Obtaining the compiler sources =
  
* Compile wasmtool.lpi
+
== Linux and MacOS ==
  
Put wasmtool somewhere in your PATH
+
The WebAssembly compiler target is part of the 'main' branch of the GitLab FPC source repo. Get the source:
 +
% git clone https://gitlab.com/freepascal.org/fpc/source.git fpc
  
And finally you need ''wasm-ld'' (don't confuse it with ''wasmld''). ToDo: Describe where to get wasm-ld.
+
Enter the sources directory:
 +
% cd fpc
  
==wasm-demo==
+
== Windows ==
Wasm-demo is a Pascal WebAssembly demo project, ported Google's C WebAssembly example (https://codelabs.developers.google.com/codelabs/web-assembly-intro)
 
  
You follow these steps in order to get the demo project working:
+
The WebAssembly compiler target is part of the 'main' branch of the GitLab FPC source repo. Get the source:
 +
C:\Users\OnlyMe> git clone https://gitlab.com/freepascal.org/fpc/source.git fpc
  
1. Get the project sources: https://github.com/skalogryz/wasm-demo
+
Enter the sources directory:
 +
C:\Users\OnlyMe> cd fpc
  
===Using in webassembly.studio===
+
= Building and installing =
2. Run the wasm compiler against lyff.pas, but request the assembler file to be kept
 
  pp -a lyff.pas
 
Webassembly.studio accepts the assembler file and would compile it on the server side.
 
  
3. open up  https://webassembly.studio and select "Create empty Wat Project". The project will consist of:
+
If you are new to building the compiler, see [[Installing the Free Pascal Compiler]] and [[Cross compiling]].
:main.html
 
:main.js
 
:main.wat
 
All files of the project can be edited through the web interface.
 
  
4. Copy and paste the contents of the following files:
+
FPC supports two WebAssembly compilation targets: WASI and embedded.
: (compiled) lyff.wat to main.wat.
 
: wasm-demo\webassembly.studio\main.html to main.html
 
: wasm-demo\webassembly.studio\main.js to main.js
 
  
Note: every time you copy and paste, don't forget to press "SAVE" button (on the right side of the web interface)
+
== Compilation target: WASI ==
  
5. once all files are update, hit "Build and Run"
+
=== Linux and MacOS ===
  
==See Also==
+
Build the compiler and FPC units for the WASI target:
 +
% make clean all OS_TARGET=wasi CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc
 +
 
 +
Then, install, using INSTALL_PREFIX to specify a destination within your home directory:
 +
% make crossinstall OS_TARGET=wasi CPU_TARGET=wasm32 INSTALL_PREFIX=$HOME/fpcwasm
 +
 
 +
Make a link to the cross compiler executable ''ppcrosswasm32'':
 +
% ln -sf ~/fpcwasm/lib/fpc/3.3.1/ppcrosswasm32 ~/bin/ppcrosswasm32
 +
 
 +
Note: This assumes you have a $HOME/bin directory and it is in PATH.
 +
 
 +
=== Windows ===
 +
 
 +
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.
 +
 
 +
Build the compiler and FPC units for the WASI target:
 +
C:\Users\OnlyMe\fpc> make clean all OS_TARGET=wasi CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc
 +
 
 +
Then, install, using INSTALL_PREFIX to specify a destination folder:
 +
C:\Users\OnlyMe\fpc> make crossinstall OS_TARGET=wasi CPU_TARGET=wasm32 INSTALL_PREFIX=c:\fpcwasm PP=fpc
 +
 
 +
Add C:\fpcwasm\bin\x86_64-win64 to your PATH to easily run the compiler ''ppcrosswasm32.exe''.
 +
 
 +
== Compilation target: Embedded  ==
 +
 
 +
=== Linux and MacOS ===
 +
 
 +
Build the compiler and FPC units for the 'embedded' target:
 +
% make clean all OS_TARGET=embedded CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc
 +
 
 +
Then, install, using INSTALL_PREFIX to specify a destination within your home directory:
 +
% make crossinstall OS_TARGET=embedded CPU_TARGET=wasm32 INSTALL_PREFIX=$HOME/fpcwasm
 +
 
 +
If you have not built and installed the WASI cross compiler, then make a link to the cross compiler executable ''ppcrosswasm32''; 
 +
% ln -sf ~/fpcwasm/lib/fpc/3.3.1/ppcrosswasm32 ~/bin/ppcrosswasm32
 +
 
 +
Note: This assumes you have a $HOME/bin directory and it is in PATH.
 +
 
 +
=== Windows ===
 +
 
 +
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.
 +
 
 +
Build the compiler and FPC units for the 'embedded' target:
 +
C:\Users\OnlyMe\fpc> make clean all OS_TARGET=embedded CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc
 +
 
 +
Then, install, using INSTALL_PREFIX to specify a destination folder:
 +
C:\Users\OnlyMe\fpc> make crossinstall OS_TARGET=embedded CPU_TARGET=wasm32 INSTALL_PREFIX=c:\fpcwasm PP=fpc
 +
 
 +
Add C:\fpcwasm\bin\x86_64-win64 to your PATH if you have not already done so.
 +
 
 +
= Using the compiler =
 +
 
 +
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.
 +
 
 +
For Ubuntu, add these lines:
 +
<pre>
 +
#ifdef cpuwasm32
 +
-Fu/home/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/*
 +
-Fu/home/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/rtl
 +
#endif
 +
</pre>
 +
 
 +
For MacOS, add these lines:
 +
<pre>
 +
#ifdef cpuwasm32
 +
-Fu/Users/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/*
 +
-Fu/Users/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/rtl
 +
#endif
 +
</pre>
 +
 
 +
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.
 +
 
 +
= Using the compiler with Lazarus =
 +
 
 +
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'':
 +
* 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''.
 +
* Config and Target / Target platform:
 +
** Target OS: Wasi
 +
** Target CPU: wasm32
 +
* Debugging / Generate info for debugger: disable (Dec 28th 2021: otherwise you will get can't find unit linfodwrf)
 +
* 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)
 +
 
 +
=See Also=
 
*[[WebAssembly]]
 
*[[WebAssembly]]
 
[[Category:WebAssembly]]
 
[[Category:WebAssembly]]

Latest revision as of 17:07, 5 April 2022

Prerequisites

The linker wasm-ld from the LLVM project. LLVM 11.0 and 12.0.1 are known to work.

Fedora

Development was done, using the Fedora packages llvm-11.0.0-1.fc33.x86_64 and lld-11.0.0-1.fc33.x86_64.

Ubuntu

Tested on Ubuntu 20.04. wasm-ld is part of package lld-12. Install it and set necessary symlinks:

% sudo apt install lld-12
% ln -sf /usr/lib/llvm-12/bin/wasm-ld ~/bin/wasm32-wasi-wasm-ld
% ln -sf /usr/lib/llvm-12/bin/wasm-ld ~/bin/wasm32-embedded-wasm-ld

Note: This assumes you have a $HOME/bin directory and it is in PATH.

MacOS

Tested on MacOS Catalina with LLVM 11. For MacPorts, wasm-ld is part of package llvm-11; upon installation it exists as wasm-ld-mp-11. Install the package and set necessary symlinks:

% sudo port install llvm-11
% ln -sf /opt/local/bin/wasm-ld-mp-11 ~/bin/wasm32-wasi-wasm-ld
% ln -sf /opt/local/bin/wasm-ld-mp-11 ~/bin/wasm32-embedded-wasm-ld

Note: This assumes you have a $HOME/bin directory and it is in PATH.

Windows 10

Tested on Windows 10 Home 21H2. Download the LLVM 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:

 C:\> cd llvm\bin
 C:\llvm\bin> mklink wasm32-wasi-wasm-ld.exe wasm-ld.exe
 C:\llvm\bin> mklink wasm32-embedded-wasm-ld.exe wasm-ld.exe

Add C:\llvm\bin to your PATH.

Obtaining the compiler sources

Linux and MacOS

The WebAssembly compiler target is part of the 'main' branch of the GitLab FPC source repo. Get the source:

% git clone https://gitlab.com/freepascal.org/fpc/source.git fpc

Enter the sources directory:

% cd fpc

Windows

The WebAssembly compiler target is part of the 'main' branch of the GitLab FPC source repo. Get the source:

C:\Users\OnlyMe> git clone https://gitlab.com/freepascal.org/fpc/source.git fpc

Enter the sources directory:

C:\Users\OnlyMe> cd fpc

Building and installing

If you are new to building the compiler, see Installing the Free Pascal Compiler and Cross compiling.

FPC supports two WebAssembly compilation targets: WASI and embedded.

Compilation target: WASI

Linux and MacOS

Build the compiler and FPC units for the WASI target:

% make clean all OS_TARGET=wasi CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc

Then, install, using INSTALL_PREFIX to specify a destination within your home directory:

% make crossinstall OS_TARGET=wasi CPU_TARGET=wasm32 INSTALL_PREFIX=$HOME/fpcwasm

Make a link to the cross compiler executable ppcrosswasm32:

% ln -sf ~/fpcwasm/lib/fpc/3.3.1/ppcrosswasm32 ~/bin/ppcrosswasm32

Note: This assumes you have a $HOME/bin directory and it is in PATH.

Windows

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.

Build the compiler and FPC units for the WASI target:

C:\Users\OnlyMe\fpc> make clean all OS_TARGET=wasi CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc

Then, install, using INSTALL_PREFIX to specify a destination folder:

C:\Users\OnlyMe\fpc> make crossinstall OS_TARGET=wasi CPU_TARGET=wasm32 INSTALL_PREFIX=c:\fpcwasm PP=fpc

Add C:\fpcwasm\bin\x86_64-win64 to your PATH to easily run the compiler ppcrosswasm32.exe.

Compilation target: Embedded

Linux and MacOS

Build the compiler and FPC units for the 'embedded' target:

% make clean all OS_TARGET=embedded CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc

Then, install, using INSTALL_PREFIX to specify a destination within your home directory:

% make crossinstall OS_TARGET=embedded CPU_TARGET=wasm32 INSTALL_PREFIX=$HOME/fpcwasm

If you have not built and installed the WASI cross compiler, then make a link to the cross compiler executable ppcrosswasm32;

% ln -sf ~/fpcwasm/lib/fpc/3.3.1/ppcrosswasm32 ~/bin/ppcrosswasm32

Note: This assumes you have a $HOME/bin directory and it is in PATH.

Windows

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.

Build the compiler and FPC units for the 'embedded' target:

C:\Users\OnlyMe\fpc> make clean all OS_TARGET=embedded CPU_TARGET=wasm32 BINUTILSPREFIX= OPT="-O-" PP=fpc

Then, install, using INSTALL_PREFIX to specify a destination folder:

C:\Users\OnlyMe\fpc> make crossinstall OS_TARGET=embedded CPU_TARGET=wasm32 INSTALL_PREFIX=c:\fpcwasm PP=fpc

Add C:\fpcwasm\bin\x86_64-win64 to your PATH if you have not already done so.

Using the compiler

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.

For Ubuntu, add these lines:

#ifdef cpuwasm32
-Fu/home/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/*
-Fu/home/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/rtl
#endif

For MacOS, add these lines:

#ifdef cpuwasm32
-Fu/Users/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/*
-Fu/Users/yourusername/fpcwasm/lib/fpc/$fpcversion/units/$fpctarget/rtl
#endif

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.

Using the compiler with Lazarus

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:

  • 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.
  • Config and Target / Target platform:
    • Target OS: Wasi
    • Target CPU: wasm32
  • Debugging / Generate info for debugger: disable (Dec 28th 2021: otherwise you will get can't find unit linfodwrf)
  • 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)

See Also