@yowasp/runtime
v9.0.54-dev
Published
Common runtime for YoWASP packages
Downloads
58
Readme
YoWASP JavaScript runtime
This package is an internal support package for the YoWASP project. It handles interfacing with the WebAssembly runtime and the supported execution environments (Node.js and the browser). If you are writing code that is not part of the YoWASP project, you should only use functions from the @yowasp/runtime/util
module.
Application API reference
All of the other JavaScript YoWASP packages use the common runtime functionality implemented here. They export the function runX
where X
is the name of the application, which can be called as:
const filesOut = await runX(args, filesIn, { stdout, stderr, decodeASCII: true });
Arguments and return value:
- The
args
argument is an array of command line arguments, e.g.['--version']
. The 0th argument (program name) is not provided, since it is fixed and determined by the application. - The
filesIn
argument is an object associating filenames with contents, e.g.{"inv.v": "module inv(input a, output o); assign o = ~a; endmodule"}
. The values can be strings or instances of Uint8Array (which specify files), or, recursively, the same kind of object (which specifies a directory). The specified files and directories are placed in the root of the virtual filesystem. - The
filesOut
return value is the same kind of object asfilesIn
, representing the state of the virtual filesystem after the application terminated. It contains all of the data provided infilesIn
as well, unless these files were modified or removed by the application.
Options:
- The
stdout
andstderr
options are functions that are called with a sequence of bytes the application prints to the standard output and standard error streams respectively, ornull
to indicate that the stream is being flushed. If specified asnull
, the output on that stream is ignored. By default, each line of text from the combined streams is printed to the debugging console. - The
decodeASCII
option determines whether the values corresponding to files infilesOut
are always instances of Uint8Array (ifdecodeASCII: false
), or whether the values corresponding to text files will be strings (ifdecodeASCII: true
). A file is considered a text file if it contains only bytes0x09
,0x0a
,0x0d
, or those in the range0x20
to0x7e
inclusive. The default isdecodeASCII: true
.
If the application returns a non-zero exit code, the exception Exit
(exported alongside the runX
function) is raised. This exception has two properties:
- The
code
property indicates the exit code. (Currently this is always 1 due to WebAssembly peculiarities.) - The
files
property represents the state of the virtual filesystem after the application terminated. This property can be used to retrieve log files or other data aiding in diagnosing the error.
Calling await runX()
(with no arguments) does not run the application, but ensures that all of the necessary resources are fetched and available for use. Once this is done, the additional overload, below, becomes available, which executes the application synchronously instead of returning a promise. This form should only be used in Web Workers and similar non-UI threads, in contexts where the use of an asynchronous API is infeasible.
const filesOut = runX(args, filesIn, { ..., synchronously: true });
Utility API reference
This package also exports utilities that are useful when running other JavaScript YoWASP packages. These can be used as:
import { lineBuffered, chunked } from '@yowasp/runtime/util';
- The
lineBuffered(processLine)
function takes a functionprocessLine(line)
that accepts a line of text (e.g.console.log
), and returns a functionprocessBytes(bytes)
that accepts aUint8Array
of encoded characters (ornull
, which is ignored). Each byte sequence ending in the\n
byte, not including it, is decoded as UTF-8 (invalid sequences are substituted with a replacement character) and passed toprocessLine()
. - The
chunked(text)
function takes text and returns a functiongetChunk(byteLength)
that slices off aUint8Array
of UTF-8 code points of the requested length and returns it. Once it exhausts the input,getChunk()
returnsnull
whenever it is called.
License
This package is covered by the ISC license.