Moonshine

How to debug remotely

  1. How it works
  2. Adding the code to your page
  3. Starting the debug server
  4. Opening the console
  5. Connecting the VM
  6. Using custom source paths
  7. Customising ports

How it works

Debugging remotely means that you can run the debug console on any machine that is on the same network as the VM. This can be very useful for debugging on devices with smaller screens.

To do this, you must first start a debug server on any machine, usually your development machine. This server will provide you with two interfaces; a port to which you connect your VM and a webpage that provides the debug console.

Once the debug server is running, you can connect to it from your VM by entering the IP address and port number of the server. Then navigate to the given url to view the debug UI.

Add the debug engine code

The debug extension can be obtained by downloading the full Moonshine project. Once dowloaded, add the following two highlighted lines to your HTML and copy the associated two files from the extension/debug folder into your project. Make sure you add the lines after you include the Moonshine VM and before you load any Lua scripts, as shown.

Note that you only need these two scripts to run remote debugging, the rest of the debug extension directory need not be included.

<script src="/js/moonshine/moonshine.min.js"></script>
<script src="/js/moonshine/extensions/debug/debug.moonshine.js"></script>
<script src="/js/moonshine/extensions/debug/remote.debug.moonshine.js"></script>
<script>
	var vm = new shine.VM();
	vm.load('./lua/hello.lua.json');
</script>

Starting the debug server

The debug server is part of the Moonshine command line interface. Follow the steps in the Getting Started guide for instructions on how to install the CLI.

To start a debug server, simply type the following into a terminal window:

$ moonshine debug

Opening the console

When you start the debug server, it will display the url of the debug console. By default, it will be available on http://127.0.0.1:1969.

Connecting the VM

Once you have the remote debug scripts embedded in the page that is running the virtual machine and you have the debug server running, you should be able to connect the two together.

To do this, take note of the IP address and port on which the server is listening for the your app, this should be displayed in your terminal window. Type these details into the form displayed in the top-right corner of your project's webpage and click "Connect". You should then see your code appear in the debug console.

Note that you can only have one VM connected to a debug server at any one point in time. You can run multiple debug servers on the same machine so long as you customise the ports you use on subsequent instances.

Using custom source paths

By default, the distillation process will remember the relative path back to yuor Lua source code and the debugger will use this to find the source associated with a file that is running in the VM. If you move either the source or distilled file, or the source is in a directory that your web server can't access, you will need to tell the debugger where to find the source code.

To do this, run the debug server from a location that has access to the source tree and point to the root folder using the -src switch.

$ moonshine debug -src ./srcroot

Note that you can point to multiple root folders delimited by semicolons. The roots will be searched in the order specified.

$ moonshine debug -src src;lib

Customising ports

You can customise the ports that your debug server uses. Add the -ap switch to specify the port on which to listen for your app and/or the -cp switch to specify the port on which to serve the console.

$ moonshine debug -ap 2000 -cp 3000