ZeroBrane

Redbean web server debugging with ZeroBrane Studio

2022-08-11T03:46:16Z

Redbean is a single file web server that runs on Linux, Windows, macOS and several other platforms and embeds Lua, SQLite, and a host of other useful components that are all available from Lua code. ZeroBrane Studio relies on Mobdebug for its debugging capabilities, which in turn requires luasocket, but redbean compiles all its components statically and doesn't yet support dynamic linking, so using luasocket wasn't an option. Fortunately, the author of redbean implemented a powerful UNIX module, which includes raw socket support, among other things. This was enough to implement a tiny Lua library that provides just enough methods to trick Mobdebug into thinking that it has luasocket available.

The redbean plugin that implements this integration is available in the plugin repository. Let's see how you can debug a Redbean script using this plugin.

]]> ZeroBrane Studio configuration.

1. Get ZeroBrane Studio (1.60+). These instructions are for Windows, but the debugging should (and have been confirmed to) work on Linux and macOS as well.

2. Get redbean plugin and save it to HOME/.zbstudio/packages/ or ZBS/packages/ folder (where ZBS is the path to ZeroBrane Studio location and HOME is the path specified by the HOME environment variable); the first option may also be preferable for Mac OS X users as the packages/ folder may be overwritten during an application upgrade.

3. If you have redbean.com executable in your project folder or in one of the folders listed in the PATH environment variable, you can skip this step; if not, you can open ZeroBrane Studio config file (Edit | Preferences | Settings: User) and set path.redbean value pointing to the location of redbean.com executable. You'll need to restart the IDE for the configuration changes to have effect.

4. Start ZeroBrane Studio (zbstudio.exe or zbstudio.sh).

Script debugging.

Let's debug a simple Redbean script:

if MDB then MDB.on() end -- only needed when debugging .init.lua code
print("Hello from ZeroBrane Studio")
local a = 1
print("Hello from Redbean", a)
-- OnHttpRequest is executed on each request
function OnHttpRequest()
  local url = GetUrl()
  Write("inside request: " .. url)
end

Save it as .init.lua, set the project directory to the folder where you saved the script (Project | Project Directory | Set From Current File) and select Redbean as the current interpreter by going to Project | Lua Interpreter | Redbean (this option is only available when you have Redbean plugin already installed).

The last step is to add .init.lua file to your redbean.com file. If you are on Linux or macOS, you can use redbean.com -A .init.lua command. If you're on Windows, use zip.com archiver to add .init.lua to redbean.com.

Now if you Run the script, you should see the following output:

Hello from ZeroBrane Studio
Hello from Redbean	1
I2022-08-10T21:01:21.214333:tool/net/redbean.c:7067:redbean:10816] (srvr) listen http://192.168.1.8:8080
I2022-08-10T21:01:21+000000:tool/net/redbean.c:7067:redbean:10816] (srvr) listen http://127.0.0.1:8080

The first two lines came from the two print calls in .init.lua and the last two are the log messages from redbean.

There are a couple of things worth mentioning: the first line with a check for MDB enables debugging of .init.lua code itself; the MDB value is only set when debugging is requested from the IDE, so it can be left in, as the script will be executed correctly outside of the IDE as well.

If you set a breakpoint on line 4 and select Debug, you should see the debugging started and suspended at line 4:

You should now be able to step through the script, look at the stack trace, and use all other debugging functionality available in ZeroBrane Studio. For example, you can use the Remote console tab to get the value of local variable and change them (as shown in the screenshot). If you continue the execution of the script (using Run) or step through the next line (using Step), you should see "Hello from Redbean 11" printed:

You can also set breakpoints inside the OnHttpRequest function, so if you set a breakpoint on line 8, execute Run and point your browser to http://localhost:8080/, you should see the execution stopped on that breakpoint (and the Output updated with a new log message from the request). You can now inspect the value of any script variable and run any other Redbean commands (like GetHeader, SetHeader and others). Every command executed in the Remote console tab is executed in the context of the actual redbean process, so if you modify the value the url variable (as shown in the next screenshot) and continue execution, you should see the result in the browser with the modified value:

When you're done with debugging, you can either stop the process using Project | Stop menu (which will stop redbean instance if it's running on the same computer) or detach the redbean process using Project | Detach (which will continue running the current process, but without debugging).

GMaps: Canvas overlays with colors

2017-01-03T02:56:33Z

Back in 2009 I made several small GoogleMaps-based projects to show drawing on top of maps using canvas tiles. Till this day I continue getting emails with questions about some of those projects, and one of the frequent requests was whether it's possible to extend the markers to use multiple colors.

You can find the code for the "original" map with 400 markers using the same color here. This map shows the markers and allows the user to mouseover them with the cursor changing its shape when passing over a marker. A slightly different mechanism is shown here, which generates real markers, but only for those tiles that are currently displayed (to limit the number of markers displayed); the demo doesn't fully work for v2 API as it seems like isHidden method has changed its behavior.

The modified map with 400 markers using multiple colors is available here. It assigns one of two colors randomly, but you can use a similar mechanism to pick the color you need based on some marker data.

Torch debugging with ZeroBrane Studio

2016-01-14T21:40:00Z

Torch is a powerful computing framework that includes various machine learning algorithms and is built on LuaJIT, so it looked like a natural fit for support in ZeroBrane Studio. Soumith Chintala already did bulk of the work with ZeroBrane Studio clone that included Torch7 interpreter with debugging support, but it required some core changes, so it couldn't be easily combined with ZeroBrane Studio.

As the plugin API was extended with new functions in the most recent versions of the IDE, it became possible to implement the integration with Torch as a plugin, which is now available in the plugin repository.

Let's see how you can debug a Torch script or an application using this plugin.

ZeroBrane Studio configuration.

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

2. Get torch plugin and save it to HOME/.zbstudio/packages/ or ZBS/packages/ folder (where ZBS is the path to ZeroBrane Studio location and HOME is the path specified by the HOME environment variable); the first option may also be preferable for Mac OS X users as the packages/ folder may be overwritten during an application upgrade.

3. If you have TORCH_BIN environment variable defined, you can skip this step; if not, you can open ZeroBrane Studio config file (Edit | Preferences | Settings: User) and set path.torch value pointing to the th executable or the directory with the torch library (libtorch);for example, path.torch = [[D:/torch7/]]. You'll need to restart the IDE for the configuration changes to have effect.

4. Start ZeroBrane Studio (zbstudio.exe or zbstudio.sh).

Script debugging.

We can now debug a simple Torch script:

local torch = require 'torch'
local data = torch.Tensor{
  {68, 24, 20},
  {74, 26, 21},
  {80, 32, 24},
}
print(data)

Save it as test.lua and set the project directory to the folder where you saved the script (Project | Project Directory | Set From Current File) and select Torch as the current interpreter by going to Project | Lua Interpreter | Torch-7 (this option is only available when the Torch plugin is installed).

Now if you Run the script, you should see the following output:

 68  24  20
 74  26  21
 80  32  24
[torch.DoubleTensor of size 3x3]

If you select Debug, you should see the debugging started at line 1 and should be able to step through the script, set breakpoints, look at the stack trace, and use all other debugging functionality available in ZeroBrane Studio. If you set a breakpoint on line 7 and run to that line, you should see something similar to the following screenshot:

For those of you familiar with ZBS-torch, the plugin provides similar functionality, but implements visualization of Torch elements in a way similar to how it's done in Torch REPL and also removes backspaces in Torch output that is shown in the Output window.

Installation complete. You may need to rest...

2016-01-13T21:31:24Z

Found this gem in my archives. This is the snapshot I took about 6 months ago after one of the Adobe Flash installs. It's interesting that the next version didn't have this glitch.

Redis Lua debugging with ZeroBrane Studio

2016-01-05T21:49:13Z

Redis is a popular open-source in-memory datastore that provides Lua scripting among its other interesting features. When I first looked into getting the debugging of Redis Lua scripts to work with ZeroBrane Studio, I wasn't able to accomplish much as the debugger used in the IDE relies on the debug library, which is not available from the Redis sandbox that runs Lua scripts.

This has changed when Salvatore Sanfilippo implemented a debugger for debugging Lua scripts running by Redis. It supports stepping through the script, setting breakpoints, inspect variables, and other functions you'd expect from a debugger. It accepts commands over the same protocol as Redis itself and provides command-line interface to work with.

Availability of this debugger in Redis made possible to create a package in ZeroBrane Studio, that would act as a proxy and forward requests to the debugger, thus enabling full access to debugging features in the IDE.

After being contacted by Itamar Haber from RedisLabs, we quickly put together a plugin for ZeroBrane Studio that you can get from the plugin repository (make sure you use ZeroBrane Studio v1.10 or later).

Itamar also put together a post with detailed instructions and a tutorial on how this integration works for debugging Redis Lua scripts with ZeroBrane Studio. Leave a comment or send me an email if you run across an issue with the integration package or have suggestions on what can be improved.

Debugging Mashape Kong plugins with ZeroBrane Studio

2015-12-23T06:12:25Z

Mashape Kong is open-source API and microservices management system based on Nginx and written in Lua that also supports Lua plugins. Dietmar Wolz put together a detailed tutorial on how ZeroBrane Studio IDE can be used to debug Kong Lua plugins.

If you are looking for debugging of Nginx Lua scripts in general, then check this earlier post for details.

ZeroBrane Studio in black

2014-07-09T23:53:39Z

A screenshot of ZeroBrane Studio in black (Ubuntu 12.04, MATE Desktop with BlackMATE theme, TomorrowNightBright ZBS theme), courtesy of naturally as shown in Moai forums. You may click on the image to see it full screen.

You can choose one from several color themes that are included with ZeroBrane Studio.

Moonscript debugging with ZeroBrane Studio

2014-06-22T04:21:26Z

Moonscript is an interesting dynamic scripting language that compiles to Lua. Moonscript can be dynamically compiled and run using a component called moonloader and because moonloader keeps a mapping between the moonscript code and the produced Lua code, I thought it could be possible to extend the debugging in ZeroBrane Studio to take that mapping into account in some way.

The version of the debugging bundled with ZeroBrane Studio v0.70+ provides a way to specify a line mapper that can be used to map the current line in the Lua code to the line number in the "original" moonscript code. This code is "injected" in the debugger when the debugging session is started, so any line number used by the debugger (whether to show the current line, set a breakpoint, or display a stack trace) goes through that mapping.

Let's see how you can now debug moonscript files.

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. Get Moonscript plugin and save it to ZBS/packages/ or HOME/.zbstudio/packages folder (where ZBS is the path to ZeroBrane Studio location and HOME is the path specified by the HOME environment variable); the second option may also be preferable for Mac OS X users as the packages/ folder may be overwritten during an application upgrade.

3. (Optional) If moon executable is in a folder listed in the PATH environment variable, you don't need to do anything as the plugin will find it; if the executable is in some other location, you may need to add path.moonscript = [[/full/path/moon.exe]] to the ZBS configuration file (Edit | Preferences | Settings: User).

4. Start ZBS (zbstudio.exe or zbstudio.sh).

Script debugging.

Let's now debug a simple three line script:

sum = (x, y) ->
  x + y
print "The sum is ", sum 10, 20

Save it as sum.moon and set the project directory to the folder where you saved the script (Project | Project Directory | Set From Current File) and select Moonscript as the current interpreter by going to Project | Lua Interpreter | Moonscript (this option is only available when the Moonscript plugin is installed).

Now if you Run the script, you should see "The sum is 30" in the output. If you select Debug, you should see the debugging started at line 1 and should be able to step through the script, set breakpoints, look at the stack trace, and use all other debugging functionality available in ZeroBrane Studio. Note that all the line numbers are from the moonscript source and not from the (dynamically) generated Lua code, as can be seen on the screenshot:

You may notice that stepping in the debugger through the moonscript code spends more time on the same line than you'd expect. One of the most prominent examples is class definitions or table comprehensions that map few lines of Moonscript code to a (potentially) large number of lines in the corresponding Lua code, which causes the debugger to stay on the same line for each "step" through the Lua code. This may be improved in the future, but for now it's something to keep in mind; if you want to get to your destination faster, you can use breakpoints.

That's not all you can use the debugger for. You can also use moonscript expressions in the Watch panel; for example, if you enter sum 10, 20, you'll see 30 as the result after sum function is defined.

But there is more. You can also execute moonscript expressions in the Remote console. As can be seen on the screenshot, you can execute sum 1, 2 and get 3 as the result. You can also execute export mult = (x, y) -> x * y and then execute mult 10, 20 to get 200 as the result. Essentially, you can use the Remote console as Moonscript REPL with access to your application state. The only current limitation with the console commands is that they need to be single commands; this is a feature of command execution in the console that "flattens" multi-line scripts into one-liners (which doesn't work well with Moonscript, because of its whitespace sensitivity).

And one more thing. Not only syntax highlighting and folding is supported to some degree (as it's based on the Coffeescript lexer), but auto-complete for Lua functions also works with both . and \ notations, so using str = "" and str\ will offer "string" methods in the auto-complete list.

This functionality is highly experimental and has been tested with Moonscript 0.2.5 and 0.2.6 using the current ZeroBrane Studio (0.70). Give it a try with your moonscript application and share your experience in the comments or using any other method that works for you.

Lapis debugging with ZeroBrane Studio

2014-06-18T04:28:11Z

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 zbstudio.sh) 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 /lua folder.

2. Download ansicolor.lua and copy it into /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 /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 (/conf/nginx.conf):

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

Make sure you replace 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 (/lua/web.lua), which may look like this:

local lapis = require("lapis")
require('mobdebug').start('192.168.1.22')
lapis.serve(require("my_app"))
require('mobdebug').done()

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 192.168.1.22).

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

local lapis = require "lapis"
local app = lapis.Application()
app:get("/", function(self)
  return "Hello world"
end)
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.

Debugging OpenResty and Nginx Lua scripts with ZeroBrane Studio

2014-05-13T04:22:05Z

ZeroBrane Studio has already been used to debug various Lua engines -- game frameworks (like Corona, Gideros, Moai, Love2d), home automation devices, wireshark scripts, Adobe Lightroom plugins, and more -- but there have been several Lua environments that I haven't tried it on. One of them is OpenResty/Nginx Lua scripts. OpenResty is a web application server built around nginx, a very fast web server, that provides non-blocking IO with various backends (Redis, Memcached, MySQL, HTTP servers, and others) and supports Lua as its scripting language.

I first tried to use the non-blocking socket API that OpenResty provides, but couldn't get the debugging to work because socket calls that were supposed to be blocking were returning too early, which was breaking the interaction between the debugger in the application and the IDE. Based on advice from Yichun Zhang (agentzh), the maintainer of the OpenResty bundle, I then tried to use the same luasocket library that ZeroBrane Studio is using and got it all working. These are the steps you can follow to try it yourself:

ZeroBrane Studio configuration.

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

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

OpenResty configuration.

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

worker_processes  1;
events {
    worker_connections  1024;
}
http {
    lua_package_path '/lualibs/?/?.lua;/lualibs/?.lua;;';
    lua_package_cpath '/bin/clibs/?.dll;;';
    server {
        location /hellolua {
           default_type 'text/plain';
           content_by_lua_file 'lua/content.lua';
        }
    }
}

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

require('mobdebug').start('192.168.1.22')
local name = ngx.var.arg_name or "Anonymous"
ngx.say("Hello, ", name, "!")
ngx.say("Done debugging.")
require('mobdebug').done()

3. Open this file (/lua/content.lua) file in the IDE and set the project directory to lua folder by going to Project | Project Directory | Set From Current File.

Script debugging.

Now start nginx and go to http://localhost/hellolua. If everything is right, you should see ZeroBrane Studio activated with the green arrow pointing to the second line (similar to what can be seen in the screenshot above). You can now set breakpoints, step through the code, look at the stack and so on.

You can also go to the remote console and run any ngx command there. For example, if you run ngx.say("Message from console") (as shown in the screenshot), you will see this text in the output after the script is done.

If you get "attempt to yield across C-call boundary" error in Nginx logs when you start debugging, try with a more recent ZeroBrane Studio (0.70+) as it includes several improvements that make debugging to work with recent versions of OpenResty.

]]> OpenResty configuration for remote debugging.

The following steps are only needed if you configure OpenResty/Nginx for remote debugging when Nginx runs on one machine and ZeroBrane Studio runs on another one. When you run both on the same machine, Nginx is using modules included with ZeroBrane Studio as those are referenced by lua_package_path and lua_package_cpath directives.

1. Copy the debugger (mobdebug.lua) and socket files. Go to /lualibs/mobdebug/ and copy mobdebug.lua to /lua/mobdebug.lua; also copy /lualibs/socket.lua to /lua/. After all this is done, the content of lua folder is going to look like this:

./
content.lua
mobdebug.lua
socket.lua

2. Copy /bin/clibs/socket/core.dll to /socket/core.dll (core.dylib and core.so files are in the bin folder as well).

Debugging Adobe Lightroom plugins with ZeroBrane Studio

2014-04-07T04:35:20Z

(This post is by Christopher Reimold, who tested and documented the details of Adobe Lightroom plugin debugging.)

Adobe Photoshop Lightroom is a photo management and editing program that offers the ability to extend its functionality through plugins written in Lua. Debugging Lightroom plugin scripts has often been a somewhat cumbersome process, in which one had to resort to printing of variables to the console in order to understand what's going on in your plugin. However, there is now the possibility to use full in-editor interactive debugging which we will briefly demonstrate in this article.

Minimally useful demo Lightroom plugin script

We use the following short script to demonstrate developing and debugging of a Lightroom (LR) plugin in ZeroBrane Studio Lua IDE. The plugin shows the exposure value to the user. To create a plugin for LR, you have to create at least two files and one directory:

(1) The Info.lua file, which is a manifest that provides information about your plugin to LR. Its name is always Info.lua.

(2) Your actual plugin, which is called ShowExposureValue.lua in this example. It is referenced from your Info.lua file, as shown in the highlighted fragment above.

Put these two files into a directory called ExposureValue.lrplugin; the directory can reside anywhere on your hard disk. The .lrplugin extension will make LR recognize this directory as a plugin. On OSX, .lrplugin directories are recognized and treated as a package (single file). This can sometimes be problematic during development, and you can thus use .lrdevplugin as an extension on OSX if you want to avoid this.

If you want to learn more about developing an LR plugin, please have a look at the Lightroom SDK, in particular the programmer's guide and the API reference.

]]> Installing and running the plugin

To make the plugin known to Lightroom, open File | Plugin-Manager. In the dialog, select Add and add your .lrplugin directory. The plugin should now show as Display Exposure Value: Installed and running in the left column. For development purposes, do check the Reload plug-in on each export option; this way you can be sure that the latest version of your script will be run. Close the dialog.

If all has gone according to plan, you should now be able to find the plugin in the menu File | Plug-in Extras | Show Exposure Value. Start the plugin by selecting this menu item, and a dialog such as the following should appear:

Preparing your script for debugging

In order to use ZeroBrane Studio (ZBS) as an interactive debugger, you now need to make some (minor) modifications to your script and environment so that the plugin and ZBS can communicate:

Copy the files Info.lua, LrMobdebug.lua, and mobdebug.lua into the following directory:
- Mac: ~/Library/Application\ Support/Adobe/Lightroom/Modules/mobdebug.lrmodule
- Windows: C:\Program Files\Adobe\Adobe Photoshop Lightroom 5.3\Modules\mobdebug.lrmodule

This module contains the LrMobdebug namespace which will enable LR to communicate with ZBS. This module is not a plugin and don't need to be installed/added as a plugin to LR.

Have a look at the file mobdebug.lrmodule you just installed. The version field in the Info.lua manifest there has to match the major.minor version number of your Lightroom installation, or the debugging will not work (as the module will not be loaded by Lightroom). So, if you're using LR 5.3, make sure you set major version in that file to 5 and minor to 3.

Changes to your script

Now, add the following line somewhere near the beginning of your plugin: local LrMobdebug = import 'LrMobdebug'. Note: Import will throw an error if this module is not present, so if you are deploying your plugin on a customer's system, you'd need to comment out or remove all calls which refer to LrMobdebug.

Add LrMobdebug.start() call at the point where you would like the debugging to start. This will connect your script, running within the Lightroom environment, to the ZeroBrane debugger server and thus enable debugging from that execution point. (Note: LrMobdebug.start() will usually act like a breakpoint, i.e. execution will stop immediately after it; if you do not want this behavior, you can use the debugger.runonstart = true configuration setting in ZeroBrane Studio in order to avoid breaking at that point.)

Add LrMobdebug.on() after the beginning of any coroutine, i.e. LrTasks.startAsyncTask(function() LrMobdebug.on() ...).

Interactive debugging with ZBS

Now, we're ready to start stepping interactively through our application.

Open ZeroBrane Studio, go to Project | Start Debugger Server and start the debugger server (if this menu item is checked or disabled, the server is already started). When your script hits the LrMobdebug.start() command, this command will connect your script to the ZeroBrane debugger server. Therefore, the debugger server must be started before executing your plugin.
Make sure your plugin script is open in ZBS.
Set the project directory to the directory of your plugin by going to Project | Project Directory | Choose... or using Project | Project Directory | Set From Current File.
Set a breakpoint in your script by clicking in the column directly to the right of the line numbers. A red circle signifies that you have successfully set a breakpoint.
Start your plugin in Lightroom, as described above. You should see a green arrow pointing to the next statement after the start() call in ZeroBrane Studio and should be able to step through the code.

Working with the debugger

Step through your program with the Step Into command, directly next to the Pause button. Step Into steps into functions, whereas Step Over steps over functions, as usual.
If you are interested in a variable, right-click it and Add Watch Expression.
The Stack Window shows the contents of the call stack.
You can rearrange windows to have the stack and watch window always in view, as shown in the screenshot below.
Select Project | Continue to continue execution of your script. It will stop at the next breakpoint, or run until termination if there is no next breakpoint.
If you want to interrupt your debugging activities for a while, you can simply stop the debugging or switch off the debugger server by unchecking Project | Start Debugger Server option (in ZBS v0.51+).

Many thanks to Dan Tull who provided details on how the debugger can be called from Adobe Lightroom to get access to the required functionality.

Corona on-device debugging with ZeroBrane Studio

2014-03-20T02:40:18Z

ZeroBrane Studio has supported Corona SDK debugging for over a year, but one of the less known features of the integration is that it supports on-device debugging in addition to debugging in the simulator.

Since you can't initiate this process from the IDE, it requires slightly different steps:

1. You need to include the debugger component (mobdebug.lua) with your application code (to allow require 'mobdebug' command to execute successfully). You can find it under lualibs/mobdebug in ZeroBrane Studio folder.

2. You need to include require('mobdebug').start("IP-address-of-computer-running-ZBS") in your code. Note that with "regular" debugging you simply include require("mobdebug").start(), but in this case you need to provide a domain name or an IP address of the computer with the IDE as this is where the debugger in the application will connect to.

3. You need to start debugger server in the IDE by going to Project | Start Debugger Server.

4. If you do debugging on Android devices, you may need to add android.permission.INTERNET permissions to the build settings, as documented here.

If you open your Lua files in the IDE and you run your application on the device, you should see the message in the IDE that debugging has started. Most of debugging functions should work (stepping, breakpoints and the stack view), but any function that requires loadstring (remote console, watches, or value tooltips) won't work and will cause a run-time error in your application.

If you want to protect yourself from those run-time errors, you may run the following command in the local console ide.debugger.options = {noshell = true, noeval = true}; this will disable remote console and watches/tooltip evaluations to avoid using loadstring in the debugger. This configuration will be in effect for any debugging started remotely and will reset when you start any debugging from the IDE itself.

A better fix would be to allow Corona SDK to support loadstring during debugging; you may upvote this feature request that asks Corona to implement this.

Gideros on-device debugging with ZeroBrane Studio

2014-03-01T03:14:13Z

Keszegh Balazs, one of Gideros forum users put together a detailed overview of using ZeroBrane Studio for debugging of Gideros applications, including on-device debugging. Take a look at the tutorial if you have any questions about Gideros debugging with ZeroBrane Studio.

Saving debugging output to a file

2013-12-08T00:19:25Z

ZeroBrane Studio is often used for remote debugging, when the application being debugged is running on a different computer or a device, and it is very convenient to be able to "redirect" its printed output to the IDE. The IDE supports this functionality and not only allows "redirecting" of the printed output, but also pretty prints the results such that local t = {a = 1, b = 2} print(t) will print {a = 1, b = 2}. This option is turned on by default for some interpreters and can be explicitly enabled using debugger.redirect configuration option.

This is all good, but what if you have a long running process and want to be able to use this "remote" printing as a log file. The plugin below allows you to do just that: it will dump all the "remote" output to a file (output.log by default) in the current project folder. It also limits the number of records in the Output window (100 by default) to allow you to generate a large number of records without taking more memory.

]]> You can save the plugin to packages/outputtofile.lua and after restarting the IDE all the remote output will be dumped to a local log file.

local filter, fname
local function append(fname, s)
  if not fname then return end
  local f = io.open(fname, "a")
    or error(("Can't open file '%s' for writing"):format(fname))
  f:write(s)
  f:close()
end

return {
  name = "Output to file",
  description = "Redirects debugging output to a file.",
  author = "Paul Kulchenko",
  version = 0.1,

  onRegister = function(self)
    local config = ide:GetConfig()
    local output = ide:GetOutput()
    local maxlines = self:GetConfig().maxlines or 100

    filter = config.debugger.outputfilter
    config.debugger.outputfilter = function(s)
      local start  = output:GetLineCount() - maxlines
      if start >= 0 then -- trim the output to the right number of lines
        local readonly = output:GetReadOnly()
        output:SetReadOnly(false)
        output:SetTargetStart(0)
        output:SetTargetEnd(output:PositionFromLine(start+1))
        output:ReplaceTarget("")
        output:SetReadOnly(readonly)
      end
      append(fname, s)
      return s
    end
  end,

  onUnRegister = function(self)
    ide:GetConfig().debugger.outputfilter = filter
  end,
  onProjectLoad = function(self, project)
    fname = MergeFullPath(project, self:GetConfig().fname or "output.log")
  end,
}

Lua package managers and integration with ZeroBrane Studio

2013-12-04T01:18:12Z

Lua ecosystem has two package managers: LuaDist and LuaRocks. Both managers allow users to install Lua and C modules and work on Windows, Mac OS X and Linux, but have some important differences in how they operate, which I'll briefly go over.

LuaDist:

Unified build system for all modules based on CMake.
Mixed binary/source distribution that allows to use whatever dependency is available in the repository.
Everything is stored in git (using github as host) including the repository manifest. Tags are used for versions and branches for binary distributions.
Provides "batteries included" binary distributions (as a successor to Lua for Windows).
Relies on few Lua modules (luasocket, lfs, lua-git) for its implementation.
Allows for building the modules manually without using LuaDist.
Can be used from a command line or as a library (local ld = require "dist"; ld.install("luaexpat"))
Uses dist.info files for package specification information (mostly for dependency tracking, no build information).
Provides support for packaging modules for distribution.
Includes about 260 projects (as of November 2013; based on the number of sub-modules in the repository).
Includes a good number of pre-compiled binaries for Windows, but many for outdated module versions.

LuaRocks:

Supports local and remote repositories.
Distributed as a Lua scripts without dependencies, but relies on Unix tools for module deployment and installation.
Uses .rockspec files as a package specification file.
Uses "native" build instructions for each rock.
Includes rocks for 330 projects (as of November 2013).
Have several repositories: main one with manual curation and rocks.moonscript repository that supports (non-curated) rock submission and download statistics.

As we are talking about Lua module distribution, I'll also mention a nice project of Pierre Chapuis: lua toolbox. It provides a list of modules with short descriptions and their endorsement by various users (along with a simple tagging mechanism).

Both systems are easy to use as command-line tools. When you have one of the package managers installed, it's a matter of running luarocks install module or luadist install module commands to get the modules you need (assuming you have the tools available and don't run into compilation issues). It is certainly possible to setup LuaDist and LuaRocks to deploy modules to the directories you need and make those directories available to your project (see for example this nice write up by Thijs Schreijer on Setting up Lua installation on Windows using Lua Rocks and ZeroBrane Studio), but I'd prefer to have something simpler for users who may be new to programming and Lua.

I teach a semester long computer science class at a local high school during summer (using Lua and ZeroBrane Studio) and sometimes want to install Lua modules like penlight to my students' computers and use them from ZeroBrane Studio. I have 18 students using their own laptops running different systems and want to be able to say "install penlight" and then make "require 'pl.strict'" to work in their Lua scripts. The coming version (v0.40) of ZeroBrane Studio (and the current master branch) integrates with LuaDist and allows you to do just that.

]]> ZeroBrane Studio now includes LuaDist module dependencies and if you install luadist plugin, you will be able to run LuaDist commands in the Local console of ZeroBrane Studio:

> luadist.install('penlight')
Running 'install' for Lua 5.1 in '...\luadist\5.1'.
Downloading repository information...
Finding out available versions of penlight...
 - trying another candidate due to: Error when resolving dependencies: Error when retrieving the info about 'penlight': Error fetching package 'penlight-1.2.1' from 'git://github.com/LuaDist/penlight.git' to '...\luadist\5.1\tmp': Binary version of module not available and using source modules disabled.
Getting penlight-1.1 (binary)...
Finding out available versions of luafilesystem...
Getting luafilesystem-1.6.2 (binary)...
Finding out available versions of alien...
Getting alien-0.7.0 (binary)...
Finding out available versions of libffi...
Getting libffi-3.0.9 (binary)...
Installation successful.
Completed in 25 second(s).

> require 'pl.strict'
{closed_module = function() --[[..skipped..]] end, make_all_strict = function() --[[..skipped..]] end, module = function() --[[..skipped..]] end} --[[table: 0x03e4b790]]

You can then use penlight modules from the console or from your Lua scripts. Some of the other commands you may use:

luadist.install('lpeg') -- install lpeg binary version for Lua 5.1 on Windows/OSX (if available) and source version on Linux.
luadist.remove('lpeg') -- remove lpeg module (for Lua 5.1)
luadist.install('lpeg', {source = true}) -- install lpeg source version (will likely get Lua as well)
luadist.install('lpeg', {source = true, debug = true}) -- include all cmake commands and verbose output
luadist.install('lpeg', {source = true, verbose = true}) -- include verbose output, but not cmake commands
luadist.install(5.2, 'lpeg', {source = true}) -- install lpeg source version for Lua 5.2 (will likely get Lua as well)
luadist.install('lua-5.1.3') -- install specific Lua version; you may need to remove the current one first using luadist.remove('lua-5.1.5') command.

You can also try other LuaDist commands show, info, search, tree, and so on. All commands that don't include Lua version will work with default Lua 5.1 interpreter and if you include 5.2, the commands will use 5.2 interpreter. Modules for Lua 5.1 and Lua 5.2 are installed into different folders, so you can use both interpreters without conflicts.

If you get an error during installation, try running the same command with debug=true option to see what the actual cmake error is.

What works:

Windows binary installs (where available) and source installations using Lua 5.1 and Lua 5.2. Tested with cmake 2.8.10+ and mingw-tdm.
OSX source installs using Lua 5.1 and Lua 5.2 (configured to build universal binaries); you'll need CMake 2.8.10+.
Linux source installs using Lua 5.1 and Lua 5.2 (both 32bit and 64bit)

What doesn't work:

Windows binary install using Lua 5.2 (this retrieves the same module as for Lua 5.1, which doesn't load)