Orca

A couple weeks ago we made Orca’s code accessible to the public. This coincided with the Handmade Network’s Wheel Reinvention Jam. The idea was that people in the community could try Orca, maybe use it as the target platform for their jam project if they were so inclined, and give us feedback.

In the end we had one jam submission using Orca: it is a visual git log tool called Dragit, by Ben Visness. Ben interfaced with git and used our canvas API to draw nice log graphs with collapsible commits, which allows condensing the history to focus on its branching structure more than on individual commits.

Despite a single entry, we also had a good number of people trying to build and use Orca, and doing small experiments with it. I want to thank everyone who engaged with that very early MVP despite all the rough spots. Your feedback is very useful! Generally, it highlighted a number of pretty important issues with the current tooling and workflow, that we’ll work on addressing moving forward.

Before diving into some of these issues, I want to mention a nice surprise of the MVP launch, which was the interest manifested by people of the Zig community. Andrew Kelley and Loris Cro worked on stream on a build.zig script for building the Orca runtime and applications, while Reuben Dunnington and Ilia Demianenko are working on proper Zig bindings. I’m looking forward to further collaboration to make building Orca apps in Zig a nice experience.

Building the runtime

Unfortunately at this stage, trying out Orca requires building the runtime yourself. Our plan was to provide precompiled binaries of the runtime, so that applications developers don’t have to care about building it, but there was only so much we could do before the jam!

Building the runtime involves building dependencies (Angle, wasm3), building our native platform layer, parsing API specification files and generating wasm binding code, and finally compiling the runtime. We tried making this process less painful by providing CI builds of Angle, and wrapping all the code generation and build steps in a Python tool. What we didn’t expect was the number of problems steming from incompatible versions and configurations of Python, and to a lesser extent compiler versions.

So it is very clear that building the runtime in CI and providing binaries is even more of a priority. We will also get rid of Python for all the “user-side tooling” (e.g. the tool which bundles your wasm modules with the runtime to make a standalone application). This way applications developers will just have to download the API files and precompiled native tools, and never have to deal with Python quirks.

On the runtime contributors’ side, it is less of a problem to have stricter requirements, such as mandating a specific version of Python. So we can continue using Python as it is for some time, but we’ll eventually want a more robust build system. There has been interest in a zig build system, which has compelling features such as being self-contained and using the same compiler for macOS and Windows, as well as handling caching and incremental builds out of the box.

Vendoring the tooling and sources

In order to build apps outside of the Orca repository, our tool allowed to “vendor” Orca sources into your own source tree. This proved to have many issues, and since we want to distribute binaries its probably not a good idea to vendor them in each app’s repository in the first place. So we’ll leave that workflow aside for now and focus on a solution relying on a system-wide install of the orca tooling, which will manage versionning and include paths better.

Confusion about what APIs are available, and the status of the standard library

There was some confusion about which APIs are available to Orca apps, as opposed to which are internal to the runtime. This is in part due to the fact that the base layer of Orca is actually a cross-platform layer that is used both by the runtime and by apps:

• The Orca runtime is built on top of this layer, targeting native platforms (macOS or Windows)
• Orca apps are built using most of the same platform layer, but targeting WebAssembly and the system interfaces exposed by the runtime.

This arrangement allows sharing a code between the runtime and apps, and making a lot of features and utilities available to apps as a core library running in “userland” (meaning they run directly in wasm). For example, all the UI system exposed to apps runs entirely in wasm, only calling out to the runtime for rendering. The runtime uses the same UI system for its debug overlay, but running natively.

However, this means it can be unclear just looking at the sources exactly what parts are intended for the runtime, or for apps, or both. This can be addressed by better documentation and clearly marking the “application API” accessible from wasm. There’s still a weird edge-case, which is our C standard library shim.

As part of our wasm core library, we compile a subset of the C standard library. This is needed in order to integrate with some external code we use in the core library (namely stb_truetype and stb_image). As a “convenience”, we allowed apps to use that C standard lib shim, for example to call malloc/free, or math functions. This has two problems:

• It set expectations that you had access to the C standard library, whereas we only have a tiny subset of it.
• It obviously only works with people coding their applications in C (which is the only truly supported language for now, but this will change)

Rather than expanding our C standard lib shim to include more and more features, we’ll want to split things more cleanly here:

• The libc shim will remain minimal and only support what we need for the Orca core library.
• Each language bindings will have to provide its own wasm freestanding standard library (providing basically everything that specific language’s standard lib contains that doesn’t call into system APIs).

Back to work

Let’s close here by reiterating a big thank you to all early testers. We’re now getting back to work fixing issues and improving the development workflow. We’re also planning the next big milestones, including support for other languages, debugging features, and more… but that will be for another post!

Until then~