Quick Start

This document help setup and run Mare quickly.

Install

Mare is consist of a few sub-projects, written in C, Lua and JavaScript, it need to build in difference platforms respectively. But also provide a project for distribution mare-runner, it build an bundle all the dependences, use out-of-box.

Support 64-bit Linux, MacOS and Windows, you can Download on Github Release page, unzip it to any folder.

Windows User

Document use Bash to run sample code, if you use cmd.exe, you need to do a little editing, suffix the command with .exe, use \ in file path.

Run the Server

Open a terminal then enter in to the unzipped folder, use node to run index.js file. Windows user can double click run.bat to run.

By default, it will use three ports on the system: 8001, 8083 and 9223, it use dbdata folder to save runtime data.

$ ./node index.js
=== Mare servers started ===
Server for Lua debugger to attach:
socket://127.0.0.1:8083
Server implement Chrome Debugger Protocol:
http://127.0.0.1:9223/
Server access Chrome DevTools Frontend:
http://127.0.0.1:8001/

Use Chrome open http://127.0.0.1:8001/, you will see the running information.

Debug Lua Code

In the example folder, there are some sample Lua code, a pre-compile Lua interpreter and binary modlues.

Use the interface provide by remotedebug.so, start() a new Debug VM enter file, for example, the Hello world program

$ cat test.lua
require('remotedebug').start('debug-test')
print('hello, world')

here use -i option, in order let interpreter stop on REPL prompt。

$ ./lua -i test.lua
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
[mare] devtools url: http://127.0.0.1:8001/devtools/inspector.html?ws=127.0.0.1:9223/session/test?project.source=example
hello, world
>

It will print devtools url, use Chrome open it, then you will see the DevTools page, now you can debug Lua like debug JavaScript in Node. On Console tab, you can see hello world output。

You can run any snippets in lua REPL prompt, try to run print(_ENV) to see what happen.

Example Folder

Include some sample codes to play

  • test-console.lua test sementic logging
  • test-funcs.lua test function usage.
  • test-pause.lua test pause by Host VM code
  • test-print.lua test print sync output
  • test-repl.lua test running code in DevTools console
  • test-table.lua test any type table
  • test-tabson.lua test table serialize
  • test-tailcall.lua test tail call