Clingo WebAssembly

Clingo compiled to WebAssembly with Emscripten. Try it online at https://observablehq.com/@cmudig/clingo or https://domoritz.github.io/clingo-wasm.

This repo combines work from two previous repos: https://github.com/Aluriak/webclingo-example and https://github.com/domoritz/wasm-clingo.

Installation and Usage

The package is an ES module. Solving runs in a worker, so all commands are asynchronous, and a long-running solve can be aborted with clingo.restart().

Node

npm install clingo-wasm or yarn add clingo-wasm.

import clingo from "clingo-wasm";

console.log(await clingo.run("a. b :- a."));

(const clingo = require("clingo-wasm") works too.)

In the Browser

Import Clingo from the JSDelivr CDN — the wasm files load from the CDN automatically:

<script type="module">
  import clingo from "https://cdn.jsdelivr.net/npm/clingo-wasm@VERSION/dist/index.web.js";

  console.log(await clingo.run("a. b :- a."));
  console.log(await clingo.run("{a; b; c}.", 0));
</script>

Bundlers pick up the package's worker and wasm files automatically as well (Vite needs worker: { format: "es" } in its config). To host the wasm file somewhere else, pass its URL to clingo.init, which throws if the wasm cannot be loaded.

Streaming Models

To receive models as Clingo finds them instead of all at once at the end, pass a callback to run:

await clingo.run("{a; b; c}.", 0, [], (model) => console.log(model.Value));

or use the stream async generator:

for await (const model of clingo.stream("{a; b; c}.", 0)) {
  console.log(model.Value);
}

Models arrive while solving, which runs in a worker in both the browser and Node.

Parallel Solving

The package ships a second build of Clingo with thread support and picks it automatically when the environment allows. Where threads are available, Clingo's parallel solving options work:

if (clingo.supportsThreads()) {
  await clingo.run("{a; b; c}.", 0, ["-t 4"]);
}

Threads need SharedArrayBuffer: in Node it is always available, in browsers only on cross-origin isolated pages served with the COOP/COEP headers. Everywhere else the single-threaded build is used and -t reports an error. Use at most navigator.hardwareConcurrency threads, and note that passing a custom wasm URL to init selects the single-threaded build.

Developers

Build WASM file

Run npm run build:wasm if you have Docker. For testing purposes, you can run scripts/build_clingo.sh from the root directory of the project.

Build and Test JavaScript

Run npm run build to build the js files. Run npm test to run tests in node.

Update Lua, Clingo, or Emscripten

Update the versions in scripts/versions.sh and in the badges in this README.md. Then push to a new branch and let GitHub actions build the new WASM file.