(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
(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:
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.lrmoduleyou 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.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.)
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 Serverand 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 Intocommand, directly next to the Pause button.
Step Intosteps into functions, whereas
Step Oversteps 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.
Project | Continueto 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 Serveroption (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.