assemblyscript / binaryen.js

A buildbot for browser & Node.js builds of Binaryen, a compiler infrastructure and toolchain library for WebAssembly.

AssemblyScript compiles a variant of TypeScript (basically JavaScript with types) to WebAssembly using Binaryen. It generates lean and mean WebAssembly modules while being just an npm install away.

About  ·  Getting started  ·  Examples  ·  Built with AssemblyScript

Contributors

Thanks to our sponsors!

Most of the maintainers and contributors do this open source work in their free time. If you use AssemblyScript for a serious task or plan to do so, and you'd like us to invest more time on it, please donate to our OpenCollective. By sponsoring this project, your logo will show up below. Thank you so much for your support!

Development instructions

A development environment can be set up by cloning the repository:

git clone https://github.com/AssemblyScript/assemblyscript.git
cd assemblyscript
npm install
npm link

The link step is optional and makes the development instance available globally. The full process is documented as part of the repository:

• Compiler instructions
• Runtime instructions
• Test instructions

binaryen.js's Issues

How do you branch to an unnamed block for traversing up one or more blocks?

In standard WAT format you can go up one block by simply providing a number for how many blocks you want to traverse up

(block
  (loop $continue
    ;; do stuff
    br_if $cond 1
    br 0
  )
)

However when using binaryen the type information on the br_if and br functions require a string for the label.
And if I try to force a number in as the first argument I get some kind of error - however because the binaryen library is minified the error log instantly blows out my CLI history so I can read the actual error message, instead my entire terminal history is filled with a single line reference.

Being able to traverse up blocks by number instead of label name would make compilation in a recursive style much easier, but instead due to this limitation of requiring the use of string labels to jump to any point I will need to keep track of the name of the block above me at any single point in time while my compiler is going into deeper and deeper levels of nested behaviour.

Module.setFeatures doesn't work with TypeScript

Hi, I was playing with binaryen.js and stumbled upon a problem when trying to enable the Multivalue feature. After a few hours of trial end error I found that values of the Features enum assumes different values when compiled with Typescript proper compared to vanilla javascript or when using TypeScript with Parcel (which uses only Babel by default).

The following code outputs 10 when compiled with TypeScript and 512 (correct) from JavaScript.

const binaryen = require("binaryen");
console.log(binaryen.Features.Multivalue);

I suspect the problem is in TypeScript definitions of binaryen.js, but I'm not sure.
Thanks.

jsdelivr desn't contain actual binaryen version. That brokes WebAssembly Studio

Current content:
https://cdn.jsdelivr.net/gh/AssemblyScript/binaryen.js/index.js

doesn't contain _BinaryenMemoryInitId object.

It seems jsdelivr re-cache content after 24 hours (however index.js updated 2 days ago). So try again later

ESM builds

Would it be possible to provide ESM builds in addition to UMD ones? ES modules are pretty widely supported both in tooling as well as natively in browsers, and it would be nice to be able to use binaryen as an ES module in browser without polluting the global namespace or using Require.js or a bundler.

Store returns an expression

Is there a specific reason why the store() method returns an expression?
I think a statement would be much more fitting.

commonjs

I have no idea when or why this package became an esm-only project but it should definitely offer both module systems or create a separate packages as converting my entire project over to esm has come with some new painpoints

Builds with Emscripten upstream are broken

In WebAssembly/binaryen#2464 Binaryen moved from a bash script to cmake for building, and now expects Emscripten upstream (latest=1.39.3 at the time of this writing). However, after updating the buildbot stuff started breaking with an assertion being hit when trying to require the compiled binaryen.js:

• Travis/Xenial with Emsdk/latest
• Travis/Bionic with Emsdk/latest
• Travis/Xenial with Docker/trzeci/emscripten-upstream
• Travis/Bionic with Docker/trzeci/emscripten-upstream
• GitHub Actions/ubuntu-latest with Emsdk/latest

AssertionError [ERR_ASSERTION]: Got unwanted exception.
Actual message: "abort(Assertion failed: *currp, at: /home/runner/work/binaryen.js/binaryen.js/binaryen/src/wasm-traversal.h,651,pushTask). Build with -s ASSERTIONS=1 for more info."

• GitHub Actions/ubuntu-latest with Emsdk/1.39.2

AssertionError [ERR_ASSERTION]: Got unwanted exception.
Actual message: "abort(Assertion failed: s, at: /home/runner/work/binaryen.js/binaryen.js/binaryen/src/emscripten-optimizer/istring.h,65,IString). Build with -s ASSERTIONS=1 for more info."

• GitHub Actions/ubuntu-latest with Emsdk/1.39.1 (not even compiling)

[  2%] Building CXX object src/wasm/CMakeFiles/wasm.dir/literal.cpp.o
shared:WARNING: ignoring -fPIC flag when not building with SIDE_MODULE or MAIN_MODULE
shared:ERROR: treating warnings as errors (-Werror)

with the issue not being reproducible with -DCMAKE_BUILD_TYPE=Debug or locally (Debian in WSL, plain Win10 with ninja).

Also seeing the following warning in most of these setups, don't know if relevant:

CMake Warning (dev) at CMakeLists.txt:225 (ADD_LIBRARY):
  ADD_LIBRARY called with SHARED option but the target platform does not
  support dynamic linking.  Building a STATIC library instead.  This may lead
  to problems.

Also tried switching make with ninja without success.

• Full log on GitHub Actions with Emsdk/latest

Any ideas?

Public interface for BinaryenModuleRead?

Hi, is it possible to provide a public interface for BinaryenModuleRead(), which deserializes a Module from a blob? It seems the binaryen._BinaryenModuleRead function is indeed present in the compiled artifacts, but I've no idea how to properly call it.

Please add a little bit more examples to the README

I currently have a problem with what the 'ptr' param is in store function.
It would be really nice if you add some other examples to the code showing just how one or two times how an api is used for similar functions.
Otherwise it is really hard for users to understand all of them

Can't we compile binaryen to WebAssembly?

Can we get a new release published to npm?

Specifically for this feature:
WebAssembly/binaryen#1274

It appears to be in the latest build but the npm module is a couple of weeks old.

TypeError: binaryenCAPI._BinaryenCallRef is not a function

I want call call_ref opcode through binaryen , but it's not provided in binaryen.js, so I refer to the way Assemblyscript uses binayen to call _BinaryenCallRef , setting binaryen_js.d.ts and binaryen_js.js, and then introduce _BinaryenCallRef to binaryen_js.js, and then setting

import Binaryen from "binaryen_js";

But when calling _BinaryenCallRef API through Binaryen ._BinaryenCallRef, it generates error below:

`TypeError: Binaryen._BinaryenCallRef is not a function`

Is this because this API hasn't been implemented yet? Is there currently a way to use this API in JS/TS?

Thanks

`binaryen.Module.br_if` appears borken

If I put a condition on a regular br statement (not sure why a regular br statement has an optional condition).
This will compile:

ctx.m.br(ctx.popBlock(), ctx.m.i32.eq(
	m.local.get(success, binaryen.i32),
	m.i32.const(0)
))

But if I use the br_if function which sounds like the variant that should have the condition.
I always get an error

m.br_if(ctx.popBlock(), ctx.m.i32.eq(
	m.local.get(success, binaryen.i32),
	m.i32.const(0)
))

I have no error messages I can give you as every time I get an error in binaryen my entire CLI history is blown out by a single line file that it's attempting to show a line reference in for the error.

Proposal: Ideally br_if should have a condition argument and br shouldn't, but you can't roll that backwithout breaking backwards compatibility. So if br_if is turely unfunctional - you should just remove it from the API completely since br does completely fulfill it's purpose.

Wrong / old atomic ops?

https://www.npmjs.com/package/binaryen#atomic-wait-and-notify-operations- documents atomic.wait and atomic.notify builders, but I can't find them either in TypeScript typings or on the actual constructed module object.

Instead, there is atomic.fence - both exposed in code and in the docs - which shouldn't be there and was removed in the proposal.

Is there any way to construct expression from text?

Is there any way to construct expression from Binaryen's s-expression text format?
It seems that it is currently only possible to construct module from Binaryen's s-expression text format.

Update TypeScript definitions and README

A bunch of new features has landed on the Binaryen side, like SIMD, that the definitions don't yet reflect. Over at AssemblyScript there isn't an immediate need to update these because the compiler uses the C-binding directly, but others using binaryen.js from JS might want these.

It is a very good project! Can you provide more code examples?

It is a very good project! Can you provide more code examples?
It's a little difficult for me to understand

Valid module fails assertions during `mod.optimize()`

I'm working on a compiler that uses binaryen.js to generate Wasm. A problem I've run into, however, is that running mod.optimize() on the generated module (which executes fine without optimization) runs into an assertion error. Running binaryen.readBinary(mod.emitBinary()).optimize() works fine, and it passes mod.validate(), so I'm not sure what the problem is. What could I be doing wrong that causes this?

The specific assertion failure is int(_id) == int(T::SpecificId). I can probably make a reproduction if totally necessary, but it'll take a bit.

Module#getFeatures() returns 0 for module using SIMD128 and bulk memory ops

There seems to be an issue with the Module#getFeatures() call when run on a module that uses features beyond the WebAssembly MVP scope. In my case, I am using SIMD128 and bulk memory optimizations. This is confirmed when I run Module#validate(), which interestingly prints out errors like:

[wasm-validator error in function xyz] unexpected false: SIMD operation (SIMD is disabled), on ...

Note that I am using binaryen.js inside a node.js script (a mocha test script that runs some smoke tests on my WebAssembly module).

Comment on Binaryen proposal

Hi there,

to avoid observed gaps between the TypeScript in this repo and the underlying JavaScript in Binaryen repo, I have submitted a PR that moves the TypeScript source to the Binaryen repo and generates the JavaScript from it, thus ensuring a single source of truth.

The PR is here WebAssembly/binaryen#6192. (If approved, that PR would be followed by a corresponding PR in this repo, adjusting for the change of source of truth for TypeScript)

It would be great if you could comment on that PR rapidly such that the Binaryen team can reach a decision on whether or not to accept the PR.

Add wasm-metadce build

As the original announcement for wasm-metadce stated, it could be used for shrinking size of Wasm in JS bundlers. /cc @kripken @surma

However, right now there are no JS/Wasm builds of wasm-metadce, and the only place it's used in remains inside Emscripten.

Could we build metadce as a JS library as part of binaryen.js bots?

Update docs

Add docs for updates introduced in #49 and #51

How do create a data section in the IR

Sorry, I am not familiar with the operations here and the document is really insufficient.

Plz help.

Some methods are undocumented

While looking for a way to pass arguments similarly to command-line --pass-arg=... param, I've noticed that Binaryen.js actually has a setPassArgument method, and it is exposed from the npm module, but it isn't documented on either the API page or in TypeScript definitions.

It seems there are quite a few more useful methods that are similarly missing from docs & typings, even though they actually exist.

Typescript no longer recognizes the binaryen.js types

Hello,

I am not sure if I am missing something or if the type definitions are broken. Prior to version 103, code such as the following used to compile properly with TypeScript:

import binaryen from "binaryen"

function defineModule(module: binaryen.Module) {
    // do something with the passed module
}

But since version 103, the above code does not compile. It says: Cannot find namespace 'binaryen', pointing to the type of the module parameter. I guess that is because the module Binaryen (formerly binaryen) is not exported anymore, but a variable of the same type is exported instead. To make the above code compile, I have to do a cumbersome change everywhere I refer to a type in my code:

import binaryen from "binaryen"

function defineModule(module: typeof binaryen.Module.prototype) {
    // do something with the passed module.
}

I could suggest a fix in a PR, but I am hoping it is just something trivial that I am missing, and that no fix is really needed.

Thanks!

How to create a stringref use string literals directly?

In WebAssembly's stringref proposal, string literals can be used like this:

(global $hey stringref (string.const "Hey"))

And this will create a global variable $hey, which represents the reference of the string "Hey". I noticed binaryen has implemented this proposal, and added C-API bindings for the expression classes last week, including StringConst and StringNew etc.

However, I don't find the corresponding expression in binaryen.js. So I wonder is there any timeline for supporting the corresponding expression, so that binaryen.js can create a stringref use string literals directly?

Release is single threaded

It looks like binary output is single threaded, is it possible to make it multithreaded like the original binaryen binary?

i64 Typescript definition incorrect for i64.const()

The documentation for i64.const states:

Module#i64.const(value: number): ExpressionRef

However the Typescript type definition (index.d.ts) for i64 says

i64: {
const(low: number, high: number): ExpressionRef;

It should say

i64: {
const(value: number): ExpressionRef;