Skip to content

Latest commit

 

History

History
66 lines (47 loc) · 3.42 KB

Architecture.md

File metadata and controls

66 lines (47 loc) · 3.42 KB
Raw

wasm-terminal Architecture Documentation

Introduction

This file documents the high-level architecture for a web based Cyclone Scheme Read-Eval-Print-Loop (REPL), wasm-terminal.

Technology

This project uses Emscripten, Web Assembly, SharedArrayBuffer, jQuery, jQuery Terminal, prism.js, and Cyclone Scheme.

Files

  • _site
    • _headers - Directs our web host, Netlify, to serve the proper HTTP headers required for Web Assembly. Unfortunately this is required to support multithreaded web assembly programs.
    • index.html - Redirect to terminal.html
    • terminal.html - A customized version of the HTML file generated by Emscripten. The bulk of the front-end code lives here.
    • terminal.js and terminal.worker.js - Supporting JavaScript files generated by Emscripten.
    • terminal.wasm - Compiled version of all of our native code. This includes the compiled Scheme code as well as the Cyclone runtime and supporting libraries.
    • jquery js - jQuery library
    • jquery.terminal js and css files - Web-based terminal.
    • prism.js and friends - JavaScript used for syntax highlighting.
  • src
    • terminal.h - Custom C code that could not be added directly to terminal.scm due to compiler limitations.
    • terminal.c - A compiled version of terminal.scm. This file is not customized so it does not necessarily need to live in source control, but it is useful to have so that we do not need to use the native Cyclone compiler to build the .wasm file
    • terminal.scm - Code for the Scheme REPL.
  • Makefile - Build directives.

Build Environment

A natively-compiled copy of Cyclone Scheme must be used to compile terminal.scm.

The Emscripten SDK is required to compile our C code to Web Assembly.

Cyclone Scheme libraries must be built using Emscripten. It is assumed these files are located in ../cyclone-bootstrap. A build-wasm.sh script is provided to build everything.

In order to create terminal.wasm, terminal.c must be compiled by Emscripten and linked to the compiled Cyclone code. make all may be used to faciliate this step.

A web hook is in place to update the project on Netlify once changes are pushed to GitHub. Netlify is used because Web Assembly SharedArrayBuffer, which is required for pthreads, will not work unless specific security headers are used to serve our content.

Data Flow

Eval

  • The JavaScript terminal receives an input string from the user.
  • JavaScript passes the string to Scheme (WASM) via sendToEval.
  • The terminal is locked. No more input is allowed during this time.
  • Scheme main loop picks up string via get-input, and:
    • Parses into a Scheme object by reading from a string port.
    • Passes the object to eval to execute the code. During this time any data written to stdout is redirected back to the JavaScript terminal via hooks.
    • After Scheme is done, ready-for-more-input is called to unlock the terminal.
    • Loop sleeps until more input is ready.

Context-Sensitive Help

  • Our Scheme (help object) function receives a request by the user for a specific identifier.
  • Scheme calls into JavaScript function helpLink to look up the identifier.
  • JavaScript finds the identifier in a pre-computed mapping and displays the link.