diff --git a/README.md b/README.md index bd0ef56bdf..9d11a9b792 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,34 @@ -![](https://avatars1.githubusercontent.com/u/28916798?s=64) AssemblyScript -================= - -[![Actions Status](https://github.com/AssemblyScript/assemblyscript/workflows/Test/badge.svg?branch=master&event=push)](https://github.com/AssemblyScript/assemblyscript/actions) [![npm](https://img.shields.io/npm/v/assemblyscript.svg?color=0074C1)](https://www.npmjs.com/package/assemblyscript) [![npm@nightly](https://img.shields.io/npm/v/assemblyscript/nightly.svg?color=0074C1)](https://www.npmjs.com/package/assemblyscript) - -**AssemblyScript** compiles a strict subset of [TypeScript](http://www.typescriptlang.org) (basically JavaScript with types) to [WebAssembly](http://webassembly.org) using [Binaryen](https://github.com/WebAssembly/binaryen). It generates lean and mean WebAssembly modules while being just an `npm install` away. - -Check out the [documentation](https://docs.assemblyscript.org) or try it out in [WebAssembly Studio](https://webassembly.studio)! - ---- - -

Our Sponsors

- - - - - - - - - - + AssemblyScript logo

-
-

Our Backers

-

- -

- -The core team members and most 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](https://opencollective.com/assemblyscript). By sponsoring this project, your logo will show up above. Thank you so much for your support! - ---- -Motivation ----------- +

AssemblyScript Compiler

-> You are now able to write WebAssembly, without learning a new language, and harness all these benefits WebAssembly might offer you. I think that is kind of powerful. [...] It [AssemblyScript] is absolutely usable, and very enjoyable! - Surma, [WebAssembly for Web Developers (Google I/O ’19)](https://youtu.be/njt-Qzw0mVY) (May 8th, 2019) - -> AssemblyScript was frictionless. Not only does it allow you to use TypeScript to write WebAssembly, [...] it also produces glue-free WebAssembly modules that are very small with decent performance. – Surma, [Replacing a hot path in your app's JavaScript with WebAssembly](https://developers.google.com/web/updates/2019/02/hotpath-with-wasm) (Feb 16, 2019) +

+ Actions Status + npm package + npm package (nightly) +

-> Perhaps the fundamental issue [to get a small .wasm file] is that JavaScript is the only language for which the Web runtime is a perfect fit. Close relatives that were designed to compile to it, like TypeScript, can be very efficient as well. But languages like C, C++, Rust, and so forth were not originally designed for that purpose. – Alon Zakai, [Small WebAssembly Binaries with Rust + Emscripten](https://kripken.github.io/blog/binaryen/2018/04/18/rust-emscripten.html) (Apr 18, 2018) +

AssemblyScript compiles a strict 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.

-> JavaScript's heyday as the only browser language is over, but most web developers are used to writing JavaScript, and learning a new syntax just to get access to WebAssembly is not (always) ideal. If only there was something in to bridge the gap… – Jani Tarvainen, [TypeScript is the bridge between JavaScript and WebAssembly](https://malloc.fi/typescript-bridge-javascript-webassembly) (Feb 20, 2018) +

+ About · + Introduction · + Quick start · + Development instructions +

-> I do think [compiling TypeScript into WASM] is tremendously useful. It allows JavaScript developers to create WASM modules without having to learn C. – Colin Eberhardt, [Exploring different approaches to building WebAssembly modules](http://blog.scottlogic.com/2017/10/17/wasm-mandelbrot.html) (Oct 17, 2017) +

Contributors

-Further resources ------------------ +

+ Contributor logos +

-* [Documentation](https://docs.assemblyscript.org)
- Introduction, quick start, examples and general usage instructions. +

Thanks to our sponsors!

-* [Development instructions](https://docs.assemblyscript.org/details/development)
- How to set up a development environment (to submit a pull request). +

Most of the core team members and most 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!

-* [Project governance](https://github.com/AssemblyScript/working-group)
- Discussions, goals, roadmaps, assets, etc. related to development and project organization. +

+ Sponsor logos +

diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index 068073e1d1..0000000000 --- a/examples/README.md +++ /dev/null @@ -1 +0,0 @@ -The examples have been moved to [their own repository](https://github.com/AssemblyScript/examples). diff --git a/lib/loader/README.md b/lib/loader/README.md index 17c789e72a..0471e3e4b0 100644 --- a/lib/loader/README.md +++ b/lib/loader/README.md @@ -1,191 +1,8 @@ -![AS](https://avatars1.githubusercontent.com/u/28916798?s=48) AssemblyScript Loader -====================== +# AssemblyScript Loader -A convenient loader for AssemblyScript modules. Demangles module exports to a friendly object structure compatible with WebIDL and TypeScript definitions and provides some useful utility to read/write data from/to memory. +npm package +npm package (nightly) -Usage ------ +A convenient loader for [AssemblyScript](https://assemblyscript.org) modules. Demangles module exports to a friendly object structure compatible with TypeScript definitions and provides useful utility to read/write data from/to memory. -```js -const loader = require("@assemblyscript/loader"); -... -``` - -API ---- - -* **instantiate**<`T`>(moduleOrBuffer: `WebAssembly.Module | BufferSource | Response | PromiseLike`, imports?: `WasmImports`): `Promise`
- Asynchronously instantiates an AssemblyScript module from anything that can be instantiated. - -* **instantiateSync**<`T`>(moduleOrBuffer: `WebAssembly.Module | BufferSource`, imports?: `WasmImports`): `ASUtil & T`
- Synchronously instantiates an AssemblyScript module from a WebAssembly.Module or binary buffer. - -* **instantiateStreaming**<`T`>(response: `Response | PromiseLike`, imports?: `WasmImports`): `Promise`
- Asynchronously instantiates an AssemblyScript module from a response, i.e. as obtained by `fetch`. - -* **demangle**<`T`>(exports: `WasmExports`, baseModule?: `Object`): `T`
- Demangles an AssemblyScript module's exports to a friendly object structure. You usually don't have to call this manually as instantiation does this implicitly. - -**Note** that `T` above can either be omitted if the structure of the module is unknown, or can reference a `.d.ts` (i.e. `typeof MyModule`) as produced by the compiler with the `-d` option. - -Besides demangling classes exported from your entry file to a handy object structure one can use like JS objects, instances are automatically populated with useful utility: - -* **_start**(): `void`
- Explicit start function if the `--explicitStart` option is used. Must be called before any other exports if present. - -* **__allocString**(str: `string`): `number`
- Allocates a new string in the module's memory and returns a reference (pointer) to it. - - ```ts - var ptr = module.__retain(module.__allocString("hello world")); - ... - module.__release(ptr); - ``` - -* **__getString**(ptr: `number`): `string`
- Copies a string's value from the module's memory. `ptr` must not be zero. - - ```ts - var str = module.__getString(ptr); - ... - ``` - -* **__getArrayBuffer**(ptr: `number`): `ArrayBuffer`
- Copies an ArrayBuffer's value from the module's memory. `ptr` must not be zero. - -* **__getArray**(ptr: `number`): `number[]`
- Copies an array's values from the module's memory. Infers the array type from RTTI. `ptr` must not be zero. - - ```ts - var arr = module.__getArray(ptr); - ... - ``` - - If the type of the array is known beforehand, the following slightly faster helpers that don't infer the type can be used: - - **__getInt8Array**(ptr: `number`): `Int8Array`
- **__getUint8Array**(ptr: `number`): `Uint8Array`
- **__getUint8ClampedArray**(ptr: `number`): `Uint8ClampedArray`
- **__getInt16Array**(ptr: `number`): `Int16Array`
- **__getUint16Array**(ptr: `number`): `Uint16Array`
- **__getInt32Array**(ptr: `number`): `Int32Array`
- **__getUint32Array**(ptr: `number`): `Uint32Array`
- **__getInt64Array**(ptr: `number`): `BigInt64Array`
- **__getUint64Array**(ptr: `number`): `BigUint64Array`
- **__getFloat32Array**(ptr: `number`): `Float32Array`
- **__getFloat64Array**(ptr: `number`): `Float64Array` - -* **__getArrayView**(ptr: `number`): `TypedArray`
- Gets a live view on the values of an array in the module's memory. Infers the array type from RTTI. `ptr` must not be zero. - - This differs from `__getArray` in that the data isn't copied but remains *live* in both directions. That's faster but also unsafe because if the array grows or becomes released, the view will no longer represent the correct memory region and modifying its values in this state will most likely corrupt memory. Use, but use with care. - - If the type of the array is known beforehand, the following slightly faster helpers that don't infer the type can be used: - - **__getInt8ArrayView**(ptr: `number`): `Int8Array`
- **__getUint8ArrayView**(ptr: `number`): `Uint8Array`
- **__getUint8ClampedArrayView**(ptr: `number`): `Uint8ClampedArray`
- **__getInt16ArrayView**(ptr: `number`): `Int16Array`
- **__getUint16ArrayView**(ptr: `number`): `Uint16Array`
- **__getInt32ArrayView**(ptr: `number`): `Int32Array`
- **__getUint32ArrayView**(ptr: `number`): `Uint32Array`
- **__getInt64ArrayView**(ptr: `number`): `BigInt64Array`
- **__getUint64ArrayView**(ptr: `number`): `BigUint64Array`
- **__getFloat32ArrayView**(ptr: `number`): `Float32Array`
- **__getFloat64ArrayView**(ptr: `number`): `Float64Array` - -* **__retain**(ptr: `number`): `number`
- Retains a reference to a managed object externally, making sure that it doesn't become collected prematurely. Returns the pointer. - -* **__release**(ptr: `number`): `void`
- Releases a previously retained reference to a managed object, allowing the runtime to collect it once its reference count reaches zero. - -* **__alloc**(size: `number`, id: `number`): `number`
- Allocates an instance of the class represented by the specified id. If you are using `MyClass` for example, the best way to know the id and the necessary size is an `export const MYCLASS_ID = idof()` and an `export const MYCLASS_SIZE = offsetof()`. Afterwards, use the respective views to assign values to the class's memory while making sure to retain interior references to other managed objects once. When done with the class, make sure to release it, which will automatically release any interior references once the class becomes collected. - - ```ts - var ptr = module.__retain(module.__alloc(module.MYCLASS_SIZE, module.MYCLASS_ID)); - const F32 = new Float32Array(module.memory.buffer); - F32[ptr + MYCLASS_BASICFIELD1_OFFSET >>> 2] = field1_value_f32; - const U32 = new Uint32Array(module.memory.buffer); - U32[ptr + MYCLASS_MANAGEDFIELD2_OFFSET >>> 2] = module.__retain(field2_value_ptr); - ... - module.__release(ptr); - ``` - -* **__allocArray**(id: `number`, values: `number[]`): `number`
- Allocates a new array in the module's memory and returns a reference (pointer) to it. - Automatically retains interior pointers. The `id` is the unique runtime id of the respective array class. If you are using `Int32Array` for example, the best way to know the id is an `export const INT32ARRAY_ID = idof()`. When done with the array, make sure to release it. - - ```ts - var ptr = module.__retain(module.__allocArray(module.INT32ARRAY, [1, 2, 3])); - ... - module.__release(ptr); - ``` - -* **__instanceof**(ptr: `number`, baseId: `number`): `boolean`
- Tests whether an object is an instance of the class represented by the specified base id. - - ```ts - if (module.__instanceof(ptr, module.MYCLASS_ID)) { - ... - } - ``` - -* **__collect**(): `void`
- Forces a cycle collection. Only relevant if objects potentially forming reference cycles are used. - -**Note** that the views like `I32` above will automatically be updated when the module's memory grows. Don't cache these if this can happen. - -**Note** that the allocation and ownership features above require the `full` (this is the default) or the `stub` runtime to be present in your module. Other runtime variations do not export this functionality without further ado (so the compiler can eliminate what's dead code). - -**Note** that references returned from exported functions have already been retained for you and the runtime expects that you release them once not needed anymore. This is also true for constructors and getters. - -**Beware that your module is likely going to explode with seemingly random errors when using the allocation and ownership features incorrectly!** - -* Use the correct ids, sizes and layouts (C-style non-packed, export `offsetof("myField")` in case of doubt) -* Clear unused memory to zero -* Retain what you allocate -* Retain interior pointers (except in `__allocArray`) -* Don't retain what's returned (is already retained for you) -* Release when you're done with something and don't ever use it again - -Examples --------- - -### Instantiating a module - -The **asynchronous API** is analogous to [WebAssembly.instantiate](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate) and [WebAssembly.instantiateStreaming](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiateStreaming) - -```js -const myModule = await loader.instantiate(myModuleBuffer, myImports); -const myModule = await loader.instantiateStreaming(fetch("myModule.wasm"), myImports); -``` - -with `loader.instantiate` actually accepting anything that can be instantiated for convenience: - -```js -const myModule = await loader.instantiate(fs.promises.readFile("myModule.wasm"), myImports); -const myModule = await loader.instantiate(fetch("myModule.wasm"), myImports); -... -``` - -If `WebAssembly.instantiateStreaming` is not supported by the environment a fallback is applied. - -The **synchronous API** utilizes [new WebAssembly.Instance](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance#Constructor_Syntax) and [new WebAssembly.Module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module#Constructor_Syntax), which is useful if the goal is to immediately re-export as a node module for example: - -```js -module.exports = loader.instantiateSync(fs.readFileSync("myModule.wasm"), myImports); -``` - -Note, though, that browsers have relatively tight limits for synchronous compilation and instantiation because these block the main thread, hence it is recommended to use the asynchronous API in browsers. - -### Usage with TypeScript definitions produced by the compiler - -The compiler is able to emit definitions using the `-d` command line option that are compatible with modules demangled by the loader, and these can be used for proper typings in development: - -```ts -import MyModule from "myModule"; // pointing at the d.ts - -const myModule = await loader.instatiate(fs.promises.readFile("myModule.wasm"), myImports); -``` +[Documentation](https://assemblyscript.org/loader.html) diff --git a/lib/parse/README.md b/lib/parse/README.md index f4e8ed1f1c..2864308a11 100644 --- a/lib/parse/README.md +++ b/lib/parse/README.md @@ -1,4 +1,4 @@ -# ![AS](https://avatars1.githubusercontent.com/u/28916798?s=48) parse +# WebAssembly Parser A WebAssembly binary parser in WebAssembly. Super small, super fast, with TypeScript support. diff --git a/lib/rtrace/README.md b/lib/rtrace/README.md index 72411f2640..326fbbe4be 100644 --- a/lib/rtrace/README.md +++ b/lib/rtrace/README.md @@ -1,4 +1,4 @@ -# ![AS](https://avatars1.githubusercontent.com/u/28916798?s=48) rtrace +# RTrace A tiny utility that records allocations, retains, releases and frees performed by the runtime and emits an error if something is off. Also checks for leaks. diff --git a/lib/sdk/README.md b/lib/sdk/README.md index 5452e1be65..8949190e40 100644 --- a/lib/sdk/README.md +++ b/lib/sdk/README.md @@ -1,13 +1,8 @@ -# ![AS](https://avatars1.githubusercontent.com/u/28916798?s=48) SDK +# Browser SDK -An overly simple SDK to use the AssemblyScript compiler on the web. This is built -to distribution files using the exact versions of the compiler and its -dependencies. +An SDK to use the AssemblyScript compiler on the web. This is built to distribution files using the exact versions of the compiler and its dependencies. -Expects [require.js](https://requirejs.org) (or compatible) on the web, -primarily targeting [WebAssembly Studio](https://webassembly.studio). Note that -consuming the source file in this directory directly does not solve any -versioning issues - use `dist/sdk.js` instead. Do not try to bundle this. +Expects [require.js](https://requirejs.org) (or compatible) on the web, primarily targeting [WebAssembly Studio](https://webassembly.studio). Note that consuming the source file in this directory directly does not solve any versioning issues - use `dist/sdk.js` instead. Do not try to bundle this. Exports ------- @@ -40,4 +35,4 @@ require( ); ``` -There is also the [SDK example](https://github.com/AssemblyScript/assemblyscript/tree/master/examples/sdk) showing how to compile some actual code. +There is also the [SDK example](https://github.com/AssemblyScript/examples/tree/master/sdk) showing how to compile some actual code. diff --git a/lib/webpack/README.md b/lib/webpack/README.md index c2022de434..733f718636 100644 --- a/lib/webpack/README.md +++ b/lib/webpack/README.md @@ -1,7 +1,6 @@ -![AS](https://avatars1.githubusercontent.com/u/28916798?s=48) webpack -================= +# Webpack loader -[webpack](https://webpack.js.org/) loader for [AssemblyScript](http://assemblyscript.org) modules. +An experimental [webpack](https://webpack.js.org/) loader for [AssemblyScript](http://assemblyscript.org) modules. Usage ----- diff --git a/package.json b/package.json index f3e802907c..31096a5f74 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "assemblyscript", - "description": "A TypeScript to WebAssembly compiler.", + "description": "Definitely not a TypeScript to WebAssembly compiler.", "keywords": [ "typescript", "webassembly", diff --git a/src/README.md b/src/README.md index c9128bdff9..7cebb382dd 100644 --- a/src/README.md +++ b/src/README.md @@ -1,3 +1,6 @@ +Compiler +======== + Portable compiler sources that compile to both JavaScript using `tsc` and, eventually, WebAssembly using `asc`. Architecture diff --git a/std/README.md b/std/README.md index 43e8a808fe..e662171659 100644 --- a/std/README.md +++ b/std/README.md @@ -1,3 +1,6 @@ +Standard library +================ + Standard library components for use with `tsc` (portable) and `asc` (assembly). Base configurations (.json) and definition files (.d.ts) are relevant to `tsc` only and not used by `asc`.