Splitting repos

[ericvergnaud]

Following up on #6192 and #6224, that are both trying, in opposite ways, to address the issue of the TypeScript API not being in sync with the JavaScript API, itself not being in sync with the C++ API.

The opposite ways are:

• move TypeScript wrapper from Binaryen.js to Binaryen and use it for generating the JavaScript wrapper, provide missing endpoints (Generate typescript #6192)
• move the wrappers away completely from Binaryen, and host them in dedicated repos (such as Binaryen.js) (Remove JS wrapper and instead export necessary functions for wrapper implementers #6224)

What appears from various comments is 2 things:

• this repo's primary concern seems to be the C++ API (then why even generate WebAssembly?)
• Binaryen.js lives in AssemblyScript org, but the AS team doesn't use it...

It smells like a perfect setup for an unmaintained API... despite the talent and goodwill of maintainers

Do we need a different governance, where the repo for the JS wrapper of the WebAssembly of the C++ API is managed by its users rather than authors who have little or no interest in it ?

To clarify the goals of such a repo:

• generate a lean WebAssembly that's in sync with the latest Binaryen C++ release (that can be used as is by wrapper authors)
• provide a TypeScript API wrapping the above WebAssembly
• provide or generate the corresponding documentation
• package it and publish for use from node, deno and browsers

Ideally, that repo would live in the WebAssembly org, but I suspect it might take months to reach consensus on that...
I'll happily create that repo (and transfer it later to WebAssembly org) if users are supportive...

[ericvergnaud]

An example of the TS/JS unsync is const dataref: Type; in index.d.ts, which does not exist in binaryen.js-post.js.
An example of the C++/JS unsync: TypeBuilder was released with v110 in Aug 22, but is not available with v116 of the JS API (proposed fixed by #6192 WIP).

[kripken]

• this repo's primary concern seems to be the C++ API (then why even generate WebAssembly?)
• Binaryen.js lives in AssemblyScript org, but the AS team doesn't use it...

Agreed that we are in an awkward position atm.

As background, we generate js/wasm here for the same reason e.g. the wabt repo does: it was easy to add, and in the same repo it's easy to keep in sync.

I would personally be ok either moving the JS from here to another repo, or moving the JS fully here. Both have advantages.

I do think automation of the C and JS APIs might be a possible reason to do everything in this repo, but that would require some investigation probably.

[ericvergnaud]

Whilst I agree that partial automation is feasible, many critical endpoints require some coding for converting JS structures into something consumable by the WebAssembly: strings, arrays...

[ericvergnaud]

As I understand it, https://github.com/WebAssembly/binaryen/blob/main/src/wasm-delegations-fields.def currently implements 94 bindings. Binaryen.ts (from the PR) has 964 occurrences of "Binaryen" so probably 950+ bindings. That's quite a massive gap...

[tlively]

The wasm-delegations-fields.def file just gives the name and type of each field in each expression class. If we generated APIs from it, those would include getters and setters for each field as well as constructors for each expression class, so it would have much greater coverage than those numbers suggest. There would still be a gap for things like types, TypeBuilder, opcodes, and operations like running passes, parsing, and emitting modules, though.

[ericvergnaud]

Hi there. Any progress on the thinking ? I believe status quo is the worst option.

[sbc100]

SWIG has been around basically forever (since that late nineties I think) but I've not used it in more than a decade.

I think its hard to create "generic" binding yes, but that also sounds like what is being discussed here, so maybe we can avoid re-inventing too much or creating new formats?

[kripken]

@phated

here's an example that was opened 2 years ago and is still sitting: #4751

Thanks for the details. Ok, looks like the status of #4751 is that there are open review comments but you ran out of time to continue work on it, and asked if someone else could volunteer, and no one has so far?

I can't personally help more there (I don't have time to work on it myself, and can't tell anyone else what to work on), but I'd say it isn't blocked but rather waiting for someone with time and interest to do the work?

More than a couple times, you've stated something like "I don't have enough expertise around the JS bindings" for changes/suggestions/feedback I've provided.

Yeah, my knowledge of the JS ecosystem is limited, I'm afraid. So I defer on JS matters to those that know better. Perhaps I wasn't clear enough about this - sorry if so - but my point is that I am not the best person to review such changes, but that just means we need to find someone that is. Among the people cc'd on this discussion are surely people with that knowledge, in particular.

Or, if we really can't find someone, we can still land things so long as we test them very carefully. I really want good PRs not to be blocked because of such reasons.

@sbc100 @CountBleck

About bindings, I think there are two levels:

1. At a low level, this repo has wasm-delegations-fields.h which describes in a declarative manner all the instructions and fields we have. Using that it is simple to automate processes that need to do something for each field, like write a C API for getters and setters for each field (handling the type properly, etc.). That is the main thing I am suggesting we do, and it would be pretty lightweight (no new bindings library).
2. There is also the higher-level question of how to make bindings for many languages at once, which SWIG is one solution for. I don't know much about it myself. But we'd need e.g. JS bindings using the Emscripten JS glue, which I doubt SWIG supports?
   2.1. Instead of SWIG, we could do JS and other language bindings using wasm-delegations-fields.h as well. It would be more work per language, but the bindings could be more optimal and idiomatic I expect.

Concretely, I'd like to automate the C API first and see how that goes before considering anything else.

[CountBleck]

SWIG looks like "C++ -> bindings code in X language". That sounds like it'd break down for something like binaryen.js, where Binaryen is compiled with Emscripten (instead of using N-API).

Ideally the format should be something that's easy for Binaryen and other projects (of any language) to work with, without introducing weird dependencies. I'm definitely not suggesting the use of some arcane, proprietary format that has an overcomplicated type system (at that point, parsing clang AST might be better :P).

Even something like ["BinaryenCallIndirect", "Expression", ["Module", "string", "Expression", "ExpressionList", "Index", "Type", "Type"]] would work, although there's definitely room to make it prettier (and parameter names would be nice). I'm thinking of something like OpenAPI, but much simpler.

[CountBleck]

@kripken

There is also the higher-level question of how to make bindings for many languages at once

I think that should be delegated to binaryen.js and such (that is, bindings should be kept separate from this repo). This is why I think the format should be simple, so anyone can create low-level wrappers around the C API with a fifty line script, and then focus on making high-level idiomatic bindings.

using the Emscripten JS glue, which I doubt SWIG supports?

Looks like you beat me to it.

[kripken]

I wrote a small proof of concept of automatic C API generation: #6291 Pretty simple to do, I think, and it could save a lot of manual effort.

[ericvergnaud]

In reading the various feedback, I don't understand why TypeScript bindings belong in this project, but OCaml, Haskell, Rust, etc bindings don't.

I guess the reason for having TypeScript in this project is because it's a better way to produce JS bindings.
Which then raises the question of why JS bindings belong to this repo ?

I personally think all language bindings should sit under the WebAssembly org, and preferably within the binaryen repo, simply because that's the best way to keep things in sync. The purpose of this discussion is to understand how it affects governance. Notably, it might require evolving from a centralized governance to a decentralized one (where experts are in charge of approvals in specific sub-areas). If that's not acceptable, then let's not do it.

As for causing problems, I'm about 95% sure that @ericvergnaud's solution is going to create a very significant amount of work for Grain's js_of_ocaml bindings since he doesn't have the arcane knowledge in making it work. Additionally, we don't want to take on additional tooling, like the typescript compiler, to get our stuff to work.

Making something that doesn't churn is the best solution for me, @ospencer, and the rest of the Grain team as we don't have the bandwidth to keep up with said churn happening in this repository.

@phated I think you might want to have a closer look ? Precisely, my proposal produces a very lean wasm wrapper, almost the same as the one you proposed (check this vs this) and I believe it wouldn't require any additional work or additional tooling. The typescript bindings live alongside, not within, and they are in no way mandatory.

[kripken]

@ericvergnaud

are you suggesting that we don't change anything to a situation that doesn't satisfy anybody ?

I think any major change should ideally have something close to consensus among the relevant people. At least we shouldn't have major objections to it. We are not that large a group of people here, so if even one or two people strongly object that means we are making things worse for a significant proportion of us, which would be unfortunate. The current situation is also not ideal, I agree, and that motivates a change, but let's aim for one that makes sense to everyone.

Let's keep discussing here, but another option might be to schedule a video chat between interested people. That sometimes helps move discussions like this forward in my experience.

[samestep]

If a video chat occurs, may I join as well? I'm using Binaryen in TypeScript to develop program transformations and am interested in this conversation.

[kripken]

@samestep Sure, sounds good.

I suggest we give it another week or so for discussion here (as there is at least one question waiting for a response atm), and if we can't reach consensus by then, then let's look into scheduling a video chat.

Meanwhile maybe all the people interested in such a chat can respond with the 👀 emoji on this comment of mine. Feel free to do so if you are a user of Binaryen's TypeScript or JavaScript APIs, or are otherwise interested in this.

[kripken]

I've sent an email to those interested in the meeting. Let me know if you are interested and somehow did not get the email (I found emails from git commit logs, so hopefully those are up to date).

[kripken]

We had a meeting about this now - thanks everyone that attended!

It was very productive I think, and we have a general plan for next steps here:

• Get automated (as much as possible) bindings working with embind, here in the Binaryen repo. We will use embind's TypeScript support to generate both JS and TS bindings. This is how we would do things today if we started from scratch, so it makes sense to try out, given the Emscripten bindings improvements in recent years.
  • I will look into the automation part (see Proof of concept for autogenerating the C API for expressions #6291) and may ask for help from @brendandahl on the embind details.
  • We should try to make these bindings as minimal as possible.
  • We may consider two versions, for the wasm file embedded in JS and not (flipping SINGLE_FILE in emcc).
• Once that is done we can evaluate the API. It will not be identical to the current one, and likely lower-level. It may then make sense to layer a friendlier JS API on top, perhaps in a separate repo like other bindings have been doing.
  • A place for such separate repos might make sense in a dedicated binaryen org (which I reserved now: https://github.com/binaryen, just in case). Another option might be in the official WebAssembly org (WebAssembly/binaryen.ts perhaps).
  • The src/wasm-delegations*.def files have a high-level description of binaryen internals in a C header (that will be used in our autogeneration). A version of that as JSON or such might make it useful for other bindings generators. I can generate that and @phated may have ideas for the format.
• When the new embind-based build is looking good, we should look into setting up builds that are published on binaryen.js on npm, migrating the package to that basically. That will take some CI work.