Roc concepts explained

This wiki explains terms and acronyms that we use on zulip and in the roc repo.

C ABI

Application Binary Interface for the C programming language.

ABI: An interface between two binary program modules that defines how data structures or computational routines are accessed in machine code.

Effect

A function has an effect or side effect if it modifies some state outside its local environment instead of only returning a value.

For example:

def foo(arg):
    print("Function input: " + str(arg))

    return arg*2

foo does not only return a value, it modifies state outside of its environment by printing to stdout.

Host

A chunk of code that is written in a non-Roc language. It must speak C ABI and is responsible for executing the Roc app. It is also responsible for implementing any actual effects that the application has, for example: printing to std out, drawing to the screen, allocating memory,...

Platform

Roc is essentially a sandboxed language. By itself, roc can not interact with the system. It is completely pure and has no side effects.

The platform is the program that calls into Roc and essentially works as a runtime for each Roc application. A platform is made of 2 parts:

• host
• roc api: This is essentialy the interface between the roc app and the platform, written in Roc. It can be thin or a full featured library to enhance roc development for the platform.

When it comes to actual execution, Roc essentially returns a chain of tasks to the platform. The platform then executes the tasks. When the Roc app has to actually run an effect, it tells that to the platform and the platform executes the effect. Then the platform runs a continuation in roc with any data from the effect, like a read line from stdin.

This separation is how we keep roc a completely pure language without a big runtime. A platform can basically be seen as a thin language runtime. Though they are likely to be very targeted and more like a framework in other languages.

When it comes to final executable generation, it is easy to think of it like this: the roc app compiles to a library and then the platform compiles into an executable that uses the library.

You can view examples of platforms here.