Skip to content
This repository has been archived by the owner on May 13, 2024. It is now read-only.

Home

Jump to bottom
Andrew Brehaut edited this page Jul 29, 2017 · 5 revisions

Developer reference

Basics

Manticore is written in a possibly slightly surprising fashion for a Javascript/Typescript project. There are few external dependancies at runtime (notably React), and the code itself is in a somewhat /functional/ style.

I do not intend to add any additional third party dependancies to the runtime codebase of the project. Any pull requests that depend on new dependancies will be viewed with skepticism. The application is already heavy weight enough as it is (largely the result of the bundled web fonts), and I don't want to add needless bloat.

To avoid some of the ambiguity about what functional style means here, all the core code operates on immutable record objects with support from the type system, and are created and processed with simple functions: pure functions minimising side effects. Theres no usage of higher kinded types, or a large library of list processing functions. There are two reasons for this functional style:

  1. I like it, and find it makes complex algorithmic code easier to reason about.
  2. The application makes use of web workers to do processing and manage access to the data sources. While you can postMessage an object that is an instance a custom class through to a worker, the structured clone algorithm will strip off any reference to the prototype/class used in its creation.

The code base is split over a number of workers, and as a result theres a shared library of code that is used for working with data that occurs on the various sides. This resides in the common codebase. See the workers section of the wiki for more information.

The project has seen a lot of change over the course of development. It started out as a logic program written in Clojure using core.logic, migrated to ClojureScript (when I realised how computationally intensive it would be), and then into TypeScript. It has also had the UI rewritten once (the initial TypeScript version was just plain objects and DOM manipulation). You'll still see some vestiges of this in the code.

Building and developing

As noted on the readme this project uses yarn as a front end to NPM to manage packages. Just run yarn after you pull from git and things should be kept up to date. I suggest adding a .git/hooks/post-merge hook with the following script to automate this:

yarn

Once you have the codebase, and dependancies (which includes the appropriate versions of the typescript and less compilers; no need to worry about system installations for these), you'll need to run gulp build once before you can begin developing: In order to have types available for the common library available for your editor it needs to be built first.

If you do not already have an editor set up for doing typescript development, I would recommend Visual Studio Code. The project is already configured to use it and it has very good support for Typescript.

If you make changes to types in common you will need to rebuild it before those types are reflected in your editor. I've found that vscode is a little aggressive about caching these types, so sometimes closing and reopening the file will get it to catch up.

To view the current state of the project in a browser I stand up a python web server in the dist directory:

$ python -m SimpleHTTPServer

This will listen on localhost at port 8000.

Manifest files

One big PITA for this project is that in order to ship it as an application that a user can install on their mobile device and that can be used offline it needs to support the application cache. There is a gulp task manifest that will automatically generate this for you, but you will discover quickly that when you reload the application in your browser it doesn't immediately pickup the changes and you will be prompted to reload (with a banner in the top of the application). Keep an eye on the developer console in your browser for logging about the application cache.

In the longer term this will need to be superseded by a service worker, but there is no support for this yet in Safari (and iOS is a primary target for this application) so it still needs to support the legacy manifest solution. See issue #45 for more information on the state of this.

Todo:

the following sections needs more information

  • allocation algorithm
  • workers
  • data and datastructures
Clone this wiki locally