A Pythonista’s Introductory Guide to WebAssembly

Follow this link: Create pycon2022-wasm Gitpod Workspace

When the option appears, press “Continue with GitHub” and authorize Gitpod to access your account. A few moments later a small notification will appear in the bottom right corner asking “Do you want to open this workspace in VS Code Desktop?”. Press “Don’t Show Again” because we’ll be using VS Code in the browser.

From now on the gitpod.io URL will take you to your Gitpod dashboard as long as you’re logged-in.

In this tutorial we’ll make frequent use of the terminal. To open a terminal window on your workspace press Ctrl-J (Windows and Linux) or Cmd-J (macOS). When using this Gitpod workspace every time you open a terminal you’ll need to type:

This command sets the environment variables that are required to correctly run the software we’ll be using during the tutorial.

The Gitpod free plan (called the “Open Source” plan) includes 50 Gitpod hours per month. One Gitpod hour allows you to use one workspace for one hour. To see your remaining hours go to your Gitpod dashboard and select the “Settings” tab and then select “Plans” from the left-hand menu. If you want to stop the workspace at any moment, press the “Gitpod” button in the bottom left corner and select “Gitpod: Stop Workspace” in the dropdown menu. Otherwise, workspaces in the free plan have a 30 minute inactivity timeout.

With all this in mind, you are now ready to continue with the rest of the tutorial.

Let’s demonstrate how to use Pyodide with some ordinary Python code. Open the pyodide/some_python_code.py, which has the following content:

Let’s run this Python code from the terminal to make sure that it works. Change the current working directory to pyodide by typing the following at the terminal:

Now, to run the Python file type:

The output should de someting like this:

Now, let’s see how to integrate it in a web page using Pyodide. Open the pyodide/index.html file and review its contents:

To see this working we need to run a web server. At the terminal type:

Click on the “Open Browser” button that appears in the bottom right-hand side of the screen. After a few seconds you should see something like this:

Press Ctrl-C at the terminal where the web server is running in order to stop it. For the moment keep it running.

Modify the get_date_and_time function in the pyodide/some_python_code.py file so that the returned time and date string is concatenated with one of the following texts:

Note that you will need to hard code your personal birthdate information into the program.

Test your code first at the terminal. Type:

If the code produces the expected output you can now test it on the web page by refreshing it. Make sure the web server is still running.

In both the binary and textual formats, the fundamental unit of code in WebAssembly is a module. In the text format, a module is represented as one big S-expression. S-expressions are a fairly old and simple textual format for representing trees, and thus we can think of a module as a tree of nodes that describe the module’s structure and its code.

Let’s see what an S-expression looks like. Each node in the tree goes inside a pair of parentheses: ( …​ ). The first label inside the parentheses tells you what type of node it is, and after that there is a space-separated list of either attributes or child nodes. For example:

In this example the node types are module, func and export. The root of the s-expression is the module node. This node has func as its only child. The func node has two children: the export node and the return attribute. Finally, the export node has only one child, which is the "myFunction" attribute. Indentation is used here to clarify the tree-structure of the s-expression.

WebAssembly programs support only four data types:

These types are used as prefixes in most WebAssembly instructions. They are also used when declaring variables, parameters, and function return types.

A stack is a data structure with two operations: push and pop. Items are pushed (inserted) onto the stack and subsequently popped (removed) from the stack in last in, first out (LIFO) order.

WebAssembly execution is defined in terms of a stack machine where the basic idea is that every instruction pushes and/or pops a certain number to/from a stack. For example, to add the numbers 7 and 5, the following three steps need to be carried out on the stack:

The following figure illustrates the three steps described above:

The actual WAT code to do this arithmetic operation would look like this:

The following code, available as wat/examples.wat, is a complete WebAssembly module with one function that computes the average of two 64-bit floating point numbers.

File: wat/examples.wat

A couple of things worth noting:

To run this WAT code we first need to translate it into a WASM binary. There are several ways we can do this. For now, let’s use the wat2wasm tool available as part of the WABT project (pronounced "wabbit").

At the terminal, make wat your current working directory by typing:

Run the WAT to WASM translator. At the terminal type:

The previous command creates the examples.wasm file. There are several options to execute this file, but, for simplicity’s sake, let’s use a program called Wasm3, which proclaims to be “the fastest WebAssembly interpreter, and the most universal runtime”. Although it’s not a just-in-time (JIT) compiler, it’s simpler to use for our current purpose.

At the terminal type:

At the wasm3> prompt call the avg2 function by typing:

The 5 and 10 are the arguments sent to the function. The following line should be printed with the expected result:

Type Ctrl-D or Ctrl-C to exit wasm3.

Add to the wat/examples.wat file a new function called avg3 that takes three 64-bit floating point arguments \(a\), \(b\), and \(c\), and returns their average.

Translate your code using wat2wasm and test it using wasm3. Check that the computed results are correct using the following values:

Add to the wat/examples.wat file a new function called fah_to_cel that takes as argument a 64-bit floating point value that corresponds to a temperature \(F\) in degrees Fahrenheit and converts it to degrees Celsius.

Translate your code using wat2wasm and test it using wasm3. Check that the computed results are correct using the following values:

An initial implementation of the chiqui_forth compiler is contained in the forth/chiqui_forth.py file.

The file forth/execute.py is a Python script that must be used when running the WASM code produced by our compiler. This is so because WASM doesn’t directly support any I/O facilities. These have to be provided by the runtime system according to our needs. We use the wasmer Python package mentioned earlier to handle the required steps to instantiate our WASM module, call its _start function, and also import the functions $print, $emit, and $input which our generated code depends on. These functions, which are actually quite small and simple, are written in Python and can be found in this script.

Let’s see how to compile and run the chiqui_forth program.

First, make forth our current working directory. At the terminal type:

Now, to run the compiler, type ./chiqui_forth.py at the terminal followed by the name of a chiqui_forth source code file. The forth/examples directory contains several chiqui_forth programs, a couple of them should work with the current version of our compiler. At the terminal type:

This creates two new files contained in the forth/examples directory: numbers.wat and numbers.wasm. You can open the forth/examples/numbers.wat file in the editor to inspect the generated WAT code. Use the execution script to run the WASM binary code. At the terminal type:

The numbers program expects the user to type in two numbers and then prints the result of adding and multiplying them together.

Follow these same steps to compile and execute the forth/examples/hello_world.4th program.

Modify the OPERATION dictionary in forth/chiqui_forth.py so that the compiler supports all the operation words presented in the following table.

Test your code by compiling and executing the forth/examples/operators.4th program. The expected output should be:

The do and loop words will allow our chiqui_forth programs to have a repetition construct similar to Python’s while statement. It’s syntax is as follows:

The \(\textit{condition}\) part is first evaluated. If the result is zero (false) the looping construct ends and program execution continues after the loop word. Otherwise the \(\textit{body}\) is executed, the \(\textit{condition}\) is evaluated once again, and the whole process is repeated. Note that the question mark (?) word is required to establish where \(\textit{condition}\) ends and \(\textit{body}\) begins.

The following example shows how to display the numbers 1 to 10.

Modify the OPERATION dictionary in forth/chiqui_forth.py so that the compiler supports the do, ?, and loop words as detailed in the next table:

Check the documentation for the block, loop, br, and i32.eqz instructions to understand how they work.

After solving exercise D and exercise E compile and execute the following three programs from the forth/examples directory to make sure everything works as expected: