Specify and document external API

[jvilk]

We should determine what we want our external API to look like.

In both Node and the browser, doppio.js should expose a global doppio object that has all of the functionality that people will need.

Preloading files is already handled separately through the BFS interface.

So far, the following seems important:

• Invoking doppioJVM like the java command line tool.
• Stoping doppioJVM (see #276).
• doppioJVM version info (see #277).

I can't think of anything else right now.

TODO:

• [x] Integrate java CLI into JVM interface.
• [x] Integrate disassembler (javap?) CLI into JVM interface.
• [x] Integrate testing CLI into JVM interface.
• [x] Split out frontend-specific util functions, or allow the frontend to inline its own copy of util.
• [x] Almondize the doppio build to expose the JVM class as a global.
  • Need to make sure we don't break the dev build...!

[jvilk]

Current obstacles to this:

• Frontend makes direct references to particular doppio modules:
  • disassembler
  • testing
  • util

We can expose the disassembler and tester through the JVM interface to fix those, and allow it to simply inline its own copy of util. This would also allow us to move option parsing for those instructions into JVM.ts and out of the console and browser frontends. Win/win.

[jvilk]

Currently blocked on process.stdout/process.stdin emulation in BrowserFS, which will allow me to use those to print to console from the disassembler/testing functions that I plan to roll into the JVM module.

...which I'm almost done implementing. Currently bugtesting to make sure it works well enough for our simple use case.

[jvilk]

I'm making good progress in the std_stream_refactor branch.

I think the API will look something like the following, exposed through a global doppio object:

interface doppio {
  // JVM constructor for direct manipulation.
  JVM: jvm.JVM;
  // Static methods that simulate the Java CLI.
  java: (args: string[], jcl_path: string, done_cb: (arg: boolean) => void, implicit_classpath?: string[], launcher_name?: string): jvm.JVM;
  javap: (args: string[], jcl_path: string, done_cb: (arg: boolean) => void, implicit_classpath?: string[], launcher_name?: string): jvm.JVM;
  javac: (args: string[], jcl_path: string, done_cb: (arg: boolean) => void, implicit_classpath?: string[], launcher_name?: string): jvm.JVM;
  test: (command_signature_tbd);
}

Something like that. I'm probably actually going to change those static functions so they take a single options object -- makes it easier to add new options without breaking API calls. But the above arguments should give you an idea behind what data needs to be passed through the API.

I'm probably going to add the following source files:

• src/doppio.ts: Defines and exports the global doppio object.
• src/java_cli.ts: Defines command line processing and JVM construction for the java command.
• src/javap_cli.ts: Defines command line processing and JVM construction for the javap command.
• src/javac_cli.ts: Defines command line processing and JVM construction for the javac command.

Overall, this will:

• Considerably reduce the code in our frontends; the browser and console frontends can be made extremely minimalistic.
• Reduce environment assumptions inside the JVM. I'm trying to remove as many util.are_in_browser checks as I can. We used to assume a particular folder structure in some places, so I'm trying to lift those decisions to the topmost API (e.g. JCL location).
• Make it much simpler for new people to integrate doppio into their websites.

[jvilk]

Checklist:

• [ ] Write wiki article on the doppio API.
• [ ] Write wiki article on integrating doppio into a new site.
• [ ] [If feasible] Distribute doppio.d.ts that contains typings for the public API.

[jvilk]

I need to change the java_cli file to use CamelCase, but I'm almost done with some nice documentation:

https://github.com/plasma-umass/doppio/wiki/Doppio-Developer-Guide

[jvilk]

The new developer guide should be enough for now, as I'm sure the interfaces for e.g. Java objects and such will be in flux as we develop further.