VisUAL2

Visual2 GitHub official Repo

Acknowledgements

Assembly Language Documentation Repo

Read the Wiki before you contribute, or for background info.

For a quick start go straight to Getting Started.

For HLP students thinking parts of their code are better than what is collected here: you are probably correct. The initial code here was pulled together quickly and mix and match was not attempted much. Put forward a proposal to replace part of this with your code by raising an issue; I will comment and almost certainly agree if you are willing to do the interface work.

The rest of the README gives a project and code overview.

Introduction

This project is loosely based on a starter template from https://github.com/filangel/arm-monaco.

The target language is F#, which is transpiled to Javascript (js) thanks to Fable v2.x. Electron is then used to convert the developed web-app to a cross-platform native application, providing access to platform-level commands (i.e. file-system, path, multiple processes), which are unavailable to (vanilla) browser web-apps.

Webpack is the module bundler, responsible for the Javascript concatenation and automated building process.

Finally, Monaco Editor is a self-contained Javascript component that implements a programmer's editor window, with many features, which the F# code can interact with.

Features

This GUI seeks to reimplement in F# the VisUAL implementation while making many improvements and changes. The code in this project is designed to be platform-independent with minimal hassle, as was VisUAL, and is distributed as separate binaries for each of the main desktop platforms generated from this project with yarn pack-all.

Whereas VisUAL uses Java to achieve platform-independence this project uses Javascript/HTML. However, in order to make code maintainable nearly all of the source is written in F#.

The project uses automated tests for its ARM emulator that are constructed using the (open) VisualRandomTestGen project. See testing in the wiki.

Project Structure: package.json

Electron bundles Chromium (View) and node.js (Engine), therefore as in every node.js project, the package.json file specifies the (Node) module dependencies.

• dependencies: node libraries that the executable code (and development code) needs
• dev-dependencies: node libraries only needed by development tools

Additionally, the section "scripts":

{
    ...
    "scripts": {
        "start": "cd src/Main && dotnet fable webpack --port free -- -w --config webpack.config.js",
        "build": "cd src/Main && dotnet fable webpack --port free -- --config webpack.config.js",
        "package": "electron-packager . visual2 --all --out=dist --no-prune --ignore=/node_modules --ignore=/src --overwrite",
    },
    ...
}

Defines the in-project shortcut commands, therefore when we use yarn <stript_key> is equivalent to calling <script_value>. For example, in the root of the project, running in the terminal yarn launch is equivalent to running electron ..

Code Structure

The source code consists of two distinct sections transpiled separately to Javascript to make a complete Electron application.

• The electron main process runs the electron parent process under the desktop native OS, it starts the app process and provides desktop access services to it.
• The electron client (app) process runs under Chromium in a simulated browser environment (isolated from the native OS).

Electron thus allows code written for a browser (HTML + Javascript) to be run as a desktop app with the additional capability of desktop filesystem access via communication between the two processes.

Both processes run Javascript under Node.

| Process | Project | Source | Executable Code| |----------|-----------|-------|----------| | electron main| ./src/main/main.fsproj | ./src/main/main.fs | ./main.js| | electron app | n/a | ./app/index.html | (no change)| | electron app | n/a | ./app/monaco-init.js | (no change)| | electron app | ./src/renderer/renderer.fsproj| ./src/renderer/*.fs | renderer.js| | electron app | ./src/emulate/emulator.fsproj | ./src/emulator/*.fs | renderer.js|

The main.fs source configures electron start-up and is boilerplate. It is transpiled to the root project directory so it can be automatically picked up by Electron.

The app code is arranged as two F# projects, Emulator and Renderer, each with its own directory. Renderer has Emulator as a dependency. The separation allows all the non-web-based code (which can equally be run and tested under .Net) to be run and tested under F# directly in addition to being transpiled and run under Electron.

The Monaco Editor component has some additional Javascript setup, mainly the syntax highlighting, which has not been ported to F# (though it should be!). All this Javascript code is contained in monaco-init.js and run before the renderer code.

Finally the GUI skeleton and the script references that run monaco-init.js and then renderer.js under Chromium are all contained in the top-level app index.html file.

The code that turns the F# project source into renderer.js is the FABLE compiler fable-compiler followed by the Node Webpack bundler that combines multiple Javascript files into a single renderer.js. Note that the FABLE compiler is distributed as a node package so gets set up automatically with other Node components.

The compile process is controlled by the above .fsproj files (defining the F# source) and ./webpack.config.js which defines how Webpack combines F# outputs for both electron main and electron app processes and where the executable code is put (see above). This is boilerplate which you do not need to change; normally the F# project files are all that needs to be modified.

webpack.config.js

The Webpack configuration file, called when yarn start is executed, fires a process that watches changes to src folder files and transpiles the F# source files to js automatically on file save. For example, the main.js file is generated by src/main/main.fs.

File Structure

src folder

src/Emulator

The emulator source F# code. This is referenced as subproject, although under FABLE it is compiled uniformly with the renderer.

src/Renderer

The web-app GUI and Monaco editor interface source code.

src/main

Contains the F# source for the Electron startup main process code (mostly boilerplate).

app folder

The web-app, view, startup files.

app/index.html

The markup code for the view. src/Renderer/Ref.fs module accesses the elements defined in this DOM tree.

app/css

CSS code to prettify the index.html elements.

app/js

The js scripts loaded by the index.html, after the DOM elements (statically defined) are rendered.

app/js/monaco-init.js

Monaco Editor setup script.

app/js/vs

This subdirectory is copied by webpack from ./node_modules/monaco-editor/min/vs.

It works around the fact that packaging tools do not understand the non-standard Monaco loader, which loads Monaco editor files. Therefore to make things work the Monaco loader dependencies are all copied to the app directly in this directory. Note that extra code in the webpack.config script to allow this.

Getting Started

If you just want to run Visual2 go to the binaries repo

1. Follow instructions to install yarn (which tell you to install Node as well).

2. Download and install the latest (2.x) Dotnet Core SDK.
   For Mac users, download and install Mono from official website (the version from brew is incomplete, may lead to MSB error on step 7).

3. Download & unzip the Visual2 repo, or if contributing clone it locally, or fork it on github and then clone it locally.

4. Navigate to the project root directory (which contains this README) in a command-line interpreter. For Windows usage make sure if possible for convenience that you have a tabbed command-line interpreter that can be started direct from file explorer within a specific directory (by right-clicking on the explorer directory view). That makes things a lot more pleasant. I recommend Hyper, for example, runs multiple tabs and will split window between two tabs, great for running start and launch scripts concurrently in a single window. Beware that under Windows Hyper uses ctrl-shift-C, ctrl-shift-V for copy and paste.

5. Fetch the required npm packages by executing yarn install. This project consistently uses yarn Node package manager instead of npm.

6. On macOS or linux ensure you have paket installed. Run setup.bat (on Windows) or sh setup.sh (on linux or macOS). This downloads and updates the submodules, and installs their packages individually (necessary because of the submodule structure), then restores the global packages. On other systems run the statements in this file (modified if needed for your system) individually. If MSB error occur while running the script (on macOS) and you were using Mono installed by brew previously, run