Lapis debugging with ZeroBrane Studio

Fresh on the heels of getting OpenResty debugging to work with ZeroBrane Studio, I thought I would take a look at Lapis debugging. Lapis is a web framework for Lua or Moonscript, which runs inside OpenResty. Leaf Corcoran just released v1.0, which got better Lua support and more extensive documentation.

Since Lapis runs inside OpenResty, I'll be using a very similar setup to what was used for OpenResty debugging while following instructions on Creating a Lapis Application with Lua page.

ZeroBrane Studio configuration.

1. Get ZeroBrane Studio (0.70+). These instructions are for Windows, but the debugging should work on Linux and OSX as well.

2. Start ZBS (zbstudio.exe or and start the debugger Project | Start Debugger Server.

Lapis configuration.

The easiest way to get Lapis and its dependencies is to use luarocks package manager and run luarocks install lapis command. You then need to make Lapis and its dependencies available to Nginx/OpenResty. If you don't have luarocks installed or prefer to do things manually, try the following:

1. Download Lapis and copy lapis folder inside of it to <NGINX>/lua folder.

2. Download ansicolor.lua and copy it into <NGINX>/lua folder.

3. Download and compile lpeg and cjson libraries and copy the resulting dynamic libraries to the same folder where you have lua51 dynamic library (.dll, .so, or .dylib). If you are using Windows and get those libraries from LuaForWindows, LuaDist, or similar binary distribution, you may need to copy <ZBS>/bin/lua5.1.dll (not lua51.dll!) to the same folder where you copied the libraries (where lua51.dll file is located). This is necessary because those dll files are likely to be linked to lua5.1.dll, but OpenResty comes with lua51.dll and this lua5.1.dll acts as a proxy.

OpenResty configuration.

1. I'm using a very basic config (<NGINX>/conf/nginx.conf):

worker_processes  1;
events {
    worker_connections  1024;
http {
    lua_package_path '<ZBS>/lualibs/?/?.lua;<ZBS>/lualibs/?.lua;;';
    lua_package_cpath '<ZBS>/bin/clibs/?.dll;;';
    server {
        location / {
            default_type 'text/html';
            content_by_lua_file 'lua/web.lua';

Make sure you replace <ZBS> with the actual path to ZeroBrane Studio location. If you are running on OSX, replace ?.dll with ?.dylib and if you are running on Linux, replace bin/clibs/?.dll with either bin/linux/x86/clibs/?.so or bin/linux/x64/clibs/?.so depending on your platform.

2. Create the file we are going to debug (<NGINX>/lua/web.lua), which may look like this:

local lapis = require("lapis")

Note that start() call takes the IP of the computer running the IDE. It uses "localhost" by default, but since your nginx instance is running there, you will need to specify the IP address of the computer running the IDE (in my case it is

3. Create the application file as described in Creating a Lapis Application with Lua (<NGINX>/lua/my_app.lua):

local lapis = require "lapis"
local app = lapis.Application()
app:get("/", function(self)
  return "Hello world"
return app

4. Open both files (web.lua and my_app.lua) in the IDE and set the project directory to lua folder by going to Project | Project Directory | Set From Current File.

If you already have a Lapis application you want to debug, you only need to update the Nginx config to include references to ZeroBrane Studio libraries and add require('mobdebug').start(....) and require('mobdebug').done() calls to web.lua file.

Script debugging.

Now start nginx and go to http://localhost/. If everything is done correctly, you should see ZeroBrane Studio activated with the green arrow pointing to the third line in the web.lua files. You can now set breakpoints, step through the code, look at the stack and so on.

Using step into command (Project | Step Into) will allow you to step into my_app.lua file. If you want the application to stop in the handler that returns "Hello world", you can set a breakpoint on line 4 and then use "Run" command (Project | Run).

Note that the browser window will be showing "waiting for..." message until the execution of web.lua file is completed, at which point you should see "Hello world" text there.

Debugging of Lapis files.

In addition to debugging your own application, you may also step through Lapis files if you are interested. If you open one of Lapis files in the IDE, you will be able to set breakpoints and step through it. You may also configure the IDE to auto-open any Lua file the control gets into by setting editor.autoactivate = true in the configuration file.

You should get a copy of my slick ZeroBrane Studio IDE.

Leave a comment

what will you say?