Welcome to the new Golem Cloud Docs! 👋
Documentation
Building Templates

Building Templates

This page describes the latest recommended way of how to build Golem Templates that are fully compatible with Golem.

💡

Golem is using the WASM component model and provides access to the outside world through WASI Preview2.

As both the component model and preview2 are work in progress, it is important to the exact version of tooling and interface definitions which are compatible with the actual version of Golem, described in this document.

Writing Templates

Any programming language that can be compiled to WASM can be used to create Golem templates. It is not necessary to have WASM component model support ready as there are external tools to convert a WASM module into a WASM component.

In order to work with standard IO, file and filesystems, random number generation, HTTP calls, etc. the chosen programming language must have library support built on WASI (opens in a new tab) - it can be WASI Preview1 (all the current implementations are targeting that), as there are external tools to wrap a WASM module using WASI Preview1 as a WASM component targeting WASI Preview2.

To use the new features of WASI Preview2 (such as sending HTTP requests) you have to explicitly depend on the WASI interfaces and write low-level code or wait until libraries get released targeting the new version.

Guest Language Support

Based on their support of WASI and the Component Model we categorize Guest Languages of Golem into 4 tiers:

Tier 1 Languages

Tier 1 languages have native support for building WASM components, working with WIT interfaces and their libraries are built on top of the latest version of WASI Preview 2

We don't have any language in this category yet, but we expect languages from the lower tiers to graduate here soon.

Tier 1 languages can fully take advantage of Golem.

Tier 2 Languages

Tier 2 languages can be compiled to WASM modules their standard library is built on WASI Preview 1 and there is a WIT binding generator available for them.

Using the binding generator Tier 2 languages can take full advantage of Golem's features:

  • They can define their own typed interface that can be invoked via Golem
  • They can use additional host interfaces such as WASI-HTTP and the Golem Promise API

This makes Tier 2 languages applicable in both actor-like and workflow-like use cases.

The currently supported Tier 2 languages are:

💡

Zig may be lifted to be a Tier 2 guest language in the near future, as it is supposed to work with bindings generated for C.

JVM languages like Java, Scala, Kotlin and Clojure could in theory be Tier 2 guest languages by using the experimental https://github.com/fermyon/teavm-wasi (opens in a new tab) but it is not working currently. However, Scala 2 is supported by first compiling to Javascript using Scala.JS and then using the Javascript tooling.

C# binding generator is under development, but was not tested with Golem yet.

Tier 3 Languages

Tier 3 languages can be compiled to WASM modules and they support WASI Preview 1 but there is no way to generate bindings for WIT interfaces.

This restricts them to only expose a single, parameterless run function and they can only access the host functionalities part of WASI Preview 1. (standard IO, files and filesystems, clock, random, cmd args / environment variables).

It is possible to pass input to these functions using the standard input and to get back their standard output as the call's results, but this function can only be called once for each worker.

Golem provides two special calling conventions for workers implemented with a tier 3 language:

  • The stdio calling convention passes the invocation's parameters through the worker's standard input, and parses it's standard output as JSON, returning as the invocation's result. A worker after an stdio invocation is no longer usable.
  • The stdio-eventloop calling convention makes it possible to implement stateful workers with a tier 3 language but it requires the worker to be implemented as a loop that in each iteration reads a single line containing the invocation parameters as JSON, and before reading the next line is responsible to write the response to the standard output as a single-line JSON.

The currently supported Tier 3 languages are:

💡

Possible other supported Tier 3 languages added in the near future are Ruby, PHP and Haskell.

Tier 4 Languages

Tier 4 languages can be compiled to WASM modules but they don't (or don't fully) support even WASI Preview 1. In case they partially support WASI, they may still be used to implement stateless single-invocation workers which could be useful as parts of a bigger Golem application to expose some platform-specific functionality or third party libraries, for example.

The currently supported Tier 4 languages are:

  • C# - does not support reading from the standard input, so the stdio and stdio-eventloop calling conventions cannot be used. Parameters can be passed via environment variables and output can be written to the standard output.

Writing and Building Templates

Please refer to the chosen guest language's subpage for more information about what tools to install and how to build Golem templates.