Crafting Your Own Compiler: From Python Logic to High-Speed WebAssembly

In this tutorial, participants will learn how to build in Python a compiler that translates a scaled-down programming language called chiqui_forth into executable WebAssembly (Wasm) code.

Wasm is a relatively new technology that can be used to create client-side and standalone applications that are efficient, secure, and portable. It’s an intermediate language for a stack-based virtual machine that uses a just-in-time (JIT) compiler to produce native machine code. Wasm provides a portable compilation target for languages such as C/C++, Rust, C#, and many others.

Although writing a compiler for a full blown programming language is a daunting task, it’s possible to write swiftly a Wasm targeting compiler for a fairly small language, chiqui_forth in this case. This tiny language is a subset of the Forth programming language, which first appeared in 1970. It’s a stack-oriented language that is programmed using Reverse Polish Notation (RPN), which happens to be quite easy to convert into Wasm.

By the end of this session, you won’t just have a Wasm file; you’ll have a new mental model for software:

No prior knowledge of compiler design, Wasm, or web development is required.

Because computers cannot natively understand human-written code, you must use either a compiler or an interpreter to translate and execute any program written in a high-level language.

A compiler is a program that reads the entire source code all at once and converts it into a separate, standalone file — such as machine code — that is ready to run at maximum speed. In contrast, an interpreter works on the fly. It reads, translates, and executes your code line by line, in real time, right while the program is running.

To understand the difference, imagine you need to read a book written in Polish, but you only speak English:

Building even a tiny compiler for a simple language is incredibly rewarding because it completely strips away the “magic” behind how programming languages work. By writing one yourself, you get to see exactly how your lines of text are broken down, organized, and turned into something a computer can run. This behind-the-scenes perspective makes you a much sharper problem solver and permanently changes the way you look at code. Ultimately, it turns you from someone who just writes software into someone who has a better understanding on how things work underneath.

A typical compiler operates as a pipeline, breaking down the source code into abstract representations before translating it into the final target language.

The compilation process is commonly divided into the following distinct phases:

WebAssembly is a binary format designed for a stack machine, serving as a virtual Instruction Set Architecture (ISA) that defines a standardized, abstract machine language for a sandboxed CPU. Engineered from its inception as a compiler target rather than a handwritten language, it allows developers to compile software from various high-level source languages into a highly portable format.

In client-side web environments, WebAssembly is not intended to replace JavaScript, but rather to complement it by offloading computationally heavy tasks while leaving standard scripting and DOM orchestration to the browser’s native engine. This collaborative design allows a host runtime to seamlessly translate the portable bytecode directly into a physical processor’s native instructions, powering high-performance applications across both client-side browsers and secure, server-side infrastructures.

Wasmtime is a specialized tool designed to run WebAssembly programs outside of a web browser. While WebAssembly was originally created to let developers run high-speed code inside web pages, tools like Wasmtime bring that same power to your regular desktop or server. Think of Wasmtime as a tiny, ultra-fast virtual machine or “sandbox”. It takes a compiled Wasm file (which could be written in languages like C++, Rust, or Go) and safely runs it at near-native speed on your operating system, keeping the code completely isolated so it cannot harm your computer.

The wasmtime PyPI package is the bridge that connects this WebAssembly runner directly to Python. Normally, Python is known for being easy to write but a bit slow for heavy math or intense processing. By installing this package, you can use Python to load a fast WebAssembly module and run its functions seamlessly right inside your Python script. This gives you the best of both worlds: you can write your main application using Python’s simple syntax, while instantly outsourcing heavy-duty tasks to lightning-fast WebAssembly modules without ever leaving your Python environment.

For most users, the standard package manager pip is the way to go. Open your terminal or command prompt and run:

Sometimes the pip command doesn’t work. Use this specific command if the one above fails:

Run the following command at the terminal to verify that Wasmtime was successfully installed:

If everything is OK, you should see the message Wasmtime installed successfully printed in your terminal.

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 long-established, simple textual format for representing trees, allowing us to view 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.

WAT supports two types of comments:

Examples:

Comments are ignored by the Wasm assembler and are used strictly for code documentation.

WebAssembly programs natively support multiple categories of data types. The core numeric types are:

These four core 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:

In WebAssembly, functions serve as the primary execution blocks. A function executes its logic by pulling arguments from the stack, performing its operations, and leaving the results on the stack for subsequent instructions.

Executing a Wasm module within Python using the wasmtime runtime requires a structured lifecycle: establishing an isolated execution environment, compiling the module, and instantiating it. Serving as a continuation of the previous example, the following code demonstrates this complete workflow by loading the resulting WAT file, instantiating it without external host imports, extracting its exported function, and safely marshaling Python arguments and results across the runtime boundary.

Add to the example.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.

Add the necessary code to the wat_launcher.py file to check that the computed results are correct using the following values:

Add to the example.wat file a new function called quadratic_root that takes three 64-bit floating point values corresponding to the coefficients \(a\), \(b\), and \(c\) of the quadratic equation \(ax^2+bx+c = 0\), and computes its first root.

Add the necessary code to the wat_launcher.py file to check that the computed results are correct using the following test cases (assume all inputs yield real roots):

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: