binaryen
Advanced tools
JavaScript version of Binaryen, a compiler infrastructure and toolchain library for WebAssembly.
binaryen.js is a port of Binaryen to the Web, allowing you to generate WebAssembly using a JavaScript API.
$> npm install binaryen
var binaryen = require("binaryen");
// Create a module with a single function
var myModule = new binaryen.Module();
myModule.addFunction("add", myModule.addFunctionType("iii", binaryen.i32, [ binaryen.i32, binaryen.i32 ]), [ binaryen.i32 ],
myModule.block(null, [
myModule.setLocal(2,
myModule.i32.add(
myModule.getLocal(0, binaryen.i32),
myModule.getLocal(1, binaryen.i32)
)
),
myModule.return(
myModule.getLocal(2, binaryen.i32)
)
])
);
myModule.addFunctionExport("add", "add");
// Optimize the module using default passes and levels
myModule.optimize();
// Validate the module
if (!myModule.validate())
throw new Error("validation error");
// Generate text format and binary
var textData = myModule.emitText();
var wasmData = myModule.emitBinary();
// Example usage with the WebAssembly API
var compiled = new WebAssembly.Module(wasmData);
var instance = new WebAssembly.Instance(compiled, {});
console.log(instance.exports.add(41, 1));
The buildbot also publishes nightly versions once a day if there have been changes. The latest nightly can be installed through
$> npm install binaryen@nightly
or you can use one of the previous versions instead if necessary.
Future features 🦄 might not be supported by all runtimes.
none: Type
The none type, e.g., void.
i32: Type
32-bit integer type.
i64: Type
64-bit integer type.
f32: Type
32-bit float type.
f64: Type
64-bit float (double) type.
auto: Type
Special type used in Module#block exclusively. Lets the API figure out a block's result type automatically.
unreachable: Type
Special type indicating unreachable code when obtaining information about an expression.
new Module(): Module
Constructs a new module.
parseText(text: string): Module
Creates a module from Binaryen's s-expression text format (not official stack-style text format).
readBinary(data: Uint8Array): Module
Creates a module from binary data.
Module#addFunctionType(name: string, resultType: Type, paramTypes: Type[]): Signature
Adds a new function type.
Module#getFunctionTypeBySignature(resultType: Type, paramTypes: Type[]): Signature
Gets an existing function type by its parametric signature. Returns 0 if there is no such function type.
Module#addFunction(name: string, functionType: Signature, varTypes: Type[], body: Expression): Function
Adds a function. varTypes indicate additional locals, in the given order.
Module#getFunction(name: string): Function
Gets a function, by name,
Module#removeFunction(name: string): void
Removes a function, by name.
Module#addFunctionImport(internalName: string, externalModuleName: string, externalBaseName: string, functionType: Signature): Import
Adds a function import.
Module#addTableImport(internalName: string, externalModuleName: string, externalBaseName: string): Import
Adds a table import. There's just one table for now, using name "0".
Module#addMemoryImport(internalName: string, externalModuleName: string, externalBaseName: string): Import
Adds a memory import. There's just one memory for now, using name "0".
Module#addGlobalImport(internalName: string, externalModuleName: string, externalBaseName: string, globalType: Type): Import
Adds a global variable import. Imported globals must be immutable.
Module#removeImport(internalName: string): void
Removes an import, by internal name.
Module#addFunctionExport(internalName: string, externalName: string): Export
Adds a function export.
Module#addTableExport(internalName: string, externalName: string): Export
Adds a table export. There's just one table for now, using name "0".
Module#addMemoryExport(internalName: string, externalName: string): Export
Adds a memory export. There's just one memory for now, using name "0".
Module#addGlobalExport(internalName: string, externalName: string): Export
Adds a global variable export. Exported globals must be immutable.
Module#removeExport(externalName: string): void
Removes an export, by external name.
Module#setFunctionTable(funcs: Function[]): void
Sets the contents of the function table. There's just one table for now, using name "0".
Module#setMemory(initial: number, maximum: number, exportName: string | null, segments: MemorySegment[]): void
Sets the memory. There's just one memory for now, using name "0". Providing exportName also creates a memory export.
Module#setStart(start: Function): void
Sets the start function.
Module#autoDrop(): void
Enables automatic insertion of drop operations where needed. Lets you not worry about dropping when creating your code.
getFunctionTypeInfo(ftype: FunctionType: FunctionTypeInfo
Obtains information about a function type.
string | nullType[]TypegetFunctionInfo(ftype: Function: FunctionInfo
Obtains information about a function.
string | nullFunctionTypeType[]TypeTypeExpressiongetImportInfo(import_: Import): ImportInfo
Obtains information about an import, always including:
ExternalKindstringstringstringAdditional properties depend on the expression's kind and are usually equivalent to the respective parameters when creating such an import:
TypeFunctionTypePossible ExternalKind values are:
ExternalKindExternalKindExternalKindExternalKindgetExportInfo(export_: Export): ExportInfo
Obtains information about an export.
ExternalKindstringstringbooleantrue if valid, otherwise prints validation errors and returns false.Module#optimize(): void
Optimizes the module using the default optimization passes.
Module#optimizeFunction(func: Function | string): void
Optimizes a single function using the default optimization passes.
Module#runPasses(passes: string[]): void
Runs the specified passes on the module.
Module#runPassesOnFunction(func: Function | string, passes: string[]): void
Runs the specified passes on a single function.
getOptimizeLevel(): number
Gets the currently set optimize level. 0, 1, 2 correspond to -O0, -O1, -O2 (default), etc.
setOptimizeLevel(level: number): void
Sets the optimization level to use. 0, 1, 2 correspond to -O0, -O1, -O2 (default), etc.
getShrinkLevel(): number
Gets the currently set shrink level. 0, 1, 2 correspond to -O0, -Os (default), -Oz.
setShrinkLevel(level: number): void
Sets the shrink level to use. 0, 1, 2 correspond to -O0, -Os (default), -Oz.
getDebugInfo(): boolean
Gets whether generating debug information is currently enabled or not.
setDebugInfo(on: boolean): void
Enables or disables debug information in emitted binaries.
Module#emitBinary(): Uint8Array
Returns the module in binary format.
Module#emitBinary(sourceMapUrl: string | null): BinaryWithSourceMap
Returns the module in binary format with its source map. If sourceMapUrl is null, source map generation is skipped.
Uint8Arraystring | nullModule#emitText(): string
Returns the module in Binaryen's s-expression text format (not official stack-style text format).
Module#emitAsmjs(): string
Returns the asm.js representation of the module.
Module#dispose(): void
Releases the resources held by the module once it isn't needed anymore.
Module#block(label: string | null, children: Expression[], resultType?: Type): Expression
Creates a block. resultType defaults to none.
Module#if(condition: Expression, ifTrue: Expression, ifFalse?: Expression): Expression
Creates an if or if/else combination.
Module#loop(label: string | null, body: Expression): Expression
Creates a loop.
Module#break(label: string, condition?: Expression, value?: Expression): Expression
Creates a break (br) to a label.
Module#switch(labels: string[], defaultLabel: string, condition: Expression, value?: Expression): Expression
Creates a switch (br_table).
Module#nop(): Expression
Creates a no-operation (nop) instruction.
Module#return(value?: Expression): Expression
Creates a return.
Module#unreachable(): Expression
Creates an unreachable instruction that will always trap.
Module#drop(value: Expression): Expression
Creates a drop of a value.
Module#select(condition: Expression, ifTrue: Expression, ifFalse: Expression): Expression
Creates a select of one of two values.
number): Expressionnumber, high: number): Expressionnumber): Expressionnumber): Expressionnumber): Expressionnumber, high: number): ExpressionModule#getLocal/get_local(index: number, type: Type): Expression
Creates a get_local for the local at the specified index. Note that we must specify the type here as we may not have created the local being called yet.
Module#setLocal/set_local(index: number, value: Expression): Expression
Creates a set_local for the local at the specified index.
Module#teeLocal/tee_local(index: number, value: Expression): Expression
Creates a tee_local for the local at the specified index. A tee differs from a set in that the value remains on the stack.
Module#getGlobal/get_global(name: string, type: Type): Expression
Creates a get_global for the global with the specified name. Note that we must specify the type here as we may not have created the global being called yet.
Module#setGlobal/set_global(name: string, value: Expression): Expression
Creates a set_global for the global with the specified name.
Expression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression, right: Expression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionExpression): ExpressionModule#call(name: string, operands: Expression[], returnType: Type): Expression
Creates a call to a function. Note that we must specify the return type here as we may not have created the function being called yet.
Module#callImport/call_import(name: string, operands: Expression[], returnType: Type): Expression
Similar to call, but calls an imported function.
Module#callIndirect/call_indirect(target: Expression, operands: Expression[], returnType: Type): Expression
Similar to call, but calls indirectly, i.e., via a function pointer, so an expression replaces the name as the called value.
number, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression, value: Expression): Expressionnumber, align: number, ptr: Expression, value: Expression): Expressionnumber, align: number, ptr: Expression, value: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression, value: Expression): Expressionnumber, align: number, ptr: Expression, value: Expression): Expressionnumber, align: number, ptr: Expression, value: Expression): Expressionnumber, align: number, ptr: Expression, value: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression, value: Expression): Expressionnumber, align: number, ptr: Expression): Expressionnumber, align: number, ptr: Expression, value: Expression): ExpressionExpressionnumber): Expressionstring): Expression 🦄number, ptr: Expression): Expressionnumber, ptr: Expression): Expressionnumber, ptr: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression): Expressionnumber, ptr: Expression): Expressionnumber, ptr: Expression): Expressionnumber, ptr: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, expected: Expression, replacement: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, expected: Expression, replacement: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, expected: Expression, replacement: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, expected: Expression, replacement: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, expected: Expression, replacement: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, expected: Expression, replacement: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, value: Expression): Expressionnumber, ptr: Expression, expected: Expression, replacement: Expression): ExpressionExpression, expected: Expression, timeout: Expression): ExpressionExpression, expected: Expression, timeout: Expression): ExpressionExpression, wakeCount: Expression): ExpressiongetExpressionId(expr: Expression): ExpressionId
Gets the id (kind) of the specified expression. Possible values are:
ExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdExpressionIdgetExpressionType(expr: Expression): Type
Gets the type of the specified expression.
getExpressionInfo(expr: Expression: ExpressionInfo
Obtains information about an expression, always including:
ExpressionIdTypeAdditional properties depend on the expression's id and are usually equivalent to the respective parameters when creating such an expression:
stringExpression[]ExpressionExpressionExpression | nullstringExpressionstringExpression | nullExpression | nullstring[]string | nullExpressionExpression | nullstringExpression[]stringExpression[]ExpressionExpression[]numberbooleannumberExpressionstringstringExpressionbooleanbooleannumbernumbernumberExpressionbooleannumbernumbernumberExpressionExpressionnumber | { low: number, high: number }numberExpressionnumberExpressionExpressionExpressionExpressionExpressionExpressionExpression | nullnumberstring | nullExpression[]numbernumbernumberExpressionExpressionnumbernumberExpressionExpressionExpressionExpressionExpressionExpressionTypeExpressionExpressionNopInfo and UnreachableInfo do not include any additional properties.
new Relooper(): Relooper
Constructs a relooper instance. This lets you provide an arbitrary CFG, and the relooper will structure it for WebAssembly.
Relooper#addBlock(code: Expression): RelooperBlock
Adds a new block to the CFG, containing the provided code as its body.
Relooper#addBranch(from: RelooperBlock, to: RelooperBlock, condition: Expression, code: Expression): void
Adds a branch from a block to another block, with a condition (or nothing, if this is the default branch to take from the origin - each block must have one such branch), and optional code to execute on the branch (useful for phis).
Relooper#addBlockWithSwitch(code: Expression, condition: Expression): RelooperBlock
Adds a new block, which ends with a switch/br_table, with provided code and condition (that determines where we go in the switch).
Relooper#addBranchForSwitch(from: RelooperBlock, to: RelooperBlock, indexes: number[], code: Expression): void
Adds a branch from a block ending in a switch, to another block, using an array of indexes that determine where to go, and optional code to execute on the branch.
Relooper#renderAndDispose(entry: RelooperBlock, labelHelper: number, module: Module): Expression
Renders and cleans up the Relooper instance. Call this after you have created all the blocks and branches, giving it the entry block (where control flow begins), a label helper variable (an index of a local we can use, necessary for irreducible control flow), and the module. This returns an expression - normal WebAssembly code - that you can use normally anywhere.
Module#addDebugInfoFileName(filename: string): number
Adds a debug info file name to the module and returns its index.
Module#getDebugInfoFileName(index: number): string | null
Gets the name of the debug info file at the specified index.
Module#setDebugLocation(func: Function, expr: Expression, fileIndex: number, lineNumber: number, columnNumber: number): void
Sets the debug location of the specified Expression within the specified Function.
Module#setAPITracing(on: boolean): void
Enables tracing of the C-API in the console. Can be very useful when filing bug reports.
Module#interpret(): void
Runs the module in the interpreter, calling the start function.
Clone the GitHub repository including submodules and install the development dependencies:
$> git clone --recursive https://github.com/AssemblyScript/binaryen.js.git
$> cd binaryen.js
$> npm install
Make sure Emscripten is properly set up on your system.
Afterwards, to build the binaryen submodule to index.js, run:
$> npm run build
To run the tests, do:
$> npm test
FAQs
Browser & Node.js builds of Binaryen, a compiler infrastructure and toolchain library for WebAssembly.
The npm package binaryen receives a total of 61,622 weekly downloads. As such, binaryen popularity was classified as popular.
We found that binaryen demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST's new password guidelines remove periodic changes and special character requirements, focusing on longer, more secure passwords for better authentication practices.
Security News
A record 2,709 developers participated in the 2024 Ruby on Rails Community Survey, revealing key tools, practices, and trends shaping the Rails ecosystem.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.