This page documents the principles of lua developement.

A note about beta

The lua API is still in beta. This has multiple implications you should be aware of when writing lua code

Basic principles

At startup, darktable will run two lua scripts

This is the only time darktable will run lua scripts by itself. Scripts can register callbacks to perform actions. See the corresponding section in LuaAPI

Debugging lua code

enabling log

the first step to debugging lua is to enable lua logging. this is is done by enabling the lua logdomain with the command line argument -d lua

analyzing data

Darktable provides some debugging helpers. Below is an example

dt_debug = require "darktable.debug" 
dt_debug.debug.debug = true

print(dt_debug.dump(_G,"Global environement")

the main function provided is darktable.debug.dump(object,name) This function returns a string that describes object. The object can be anything and this function will use its knowledge of the DT API to be smart about the type of objects

the boolean variable darktable.debug.debug is a boolean initialized to false. When this variable is true, dt_debug.dump will also dump metatables for objects. You usually only want to see this to debug the internals of darktable's lua API

debugging unnprotected calls

when experimenting with lua, darktable might crash with the following message :

PANIC: unprotected error in call to Lua API (some message here)

this is always a bug in the lua API. Please open a bug report and attach the script that caused it to the bug report

Handling scripts

darktable will look for lua modules in the system provided lua path, but it will also look into the following places

In other words, if you place a file called c.lua in the directory ~/.config/darktable/lua/a/b/ then require "a.b.c" will find your script.

The normal way to install a script is to copy it in ~/.config/darktable/lua/ then adding a require line to the file ~/.config/darktable/luarc

Yielding from lua code

Lua code in DT is allowed to yield (see the yield system call in the lua documentation)

Lua code that yields allows other lua callbacks to run, be aware of that

It is important to yield whenever you have some code that you expect to block to allow other lua code to run.

In particular you should always yield when calling an external program, particularly if it's a long, image processing task.

see LuaAPI for details about the syntax of the yield call in Darktable