Using Lua / LuCI
- Lua Reference
- Programming in Lua (online, packages and modules chapter)
- lua-users wiki (tutorial directory)
- LuCI Documentation (modules tutorial, modules reference, API documentation)
Lua is a fast lightweight bytecode-interpreter scripting language. It is easy to learn for people that have already worked with similar dynamic scripting languages like Python or PHP. The Fon-ng firmware makes heavy use of the Lua language in its system configuration and web user interface. LuCI is an embedded rapid application development framework written in Lua and C with a focus on web development tasks.
Introduction to Lua
There are several useful books and tutorials available to become familiar with the Lua programming language. The book Programming in Lua which is also available online is a good start for Lua beginners as well as for experienced programmers wanting to learn about the Lua C-library. Lua 5.1 introduced a new concept of modules and packages which is described in an excerpt of the printed version of "Programming in Lua".
Another important resource is of course the official Lua 5.1 Reference Manual including an overview over basic Lua concepts and a detailed API-Reference.
Sourcecode and Bytecode
Lua software can be supplied either in source code, bytecode or stripped bytecode form.
While all 3 forms result in the same program being executed there are several advantages and disadvantages:
- Sourcecode distribution is most useful for debugging and testing builds as you can directly edit the code, see in-line comments and get detailed stack traces, filenames and line numbers while debugging. However sourcecode distribution results in a substantially higher installation size and in a higher CPU consumption as every Lua file must be compiled into bytecode before execution.
- Bytecode distribution also gives you full stack-traces, filenames and linenumbers while debugging. But due to its binary form you cannot directly edit the code for testing without replacing the whole file with its sourcecode form. In exchange you will benefit of the lower CPU consumption of your programs as all files come in a precompiled form and can be directly executed by the Lua VM. Installation size is nearly equivalent to sourcecode distribution.
- Stripped bytecode distribution is basically the same as bytecode distribution but without debugging symbols. Therefore you have reduced CPU consumption and a smaller installation size but do not get detailed stacktraces, filenames and source code line numbers while debugging.
You can use the Lua compiler shipped with the Fon-ng OpenWrt buildroot to create bytecode compiled Lua files. DO NOT use the Lua compiler that comes with your Linux distribution as Fon-ng uses an optimized Lua version for embedded systems that requires a bytecode format different from the original Lua.
All preinstalled Lua applications in the Fon-ng firmware are included in the stripped bytecode form while the sourcecode can be found in the Fonosfera SVN repository.
Introduction to LuCI
To get started with LuCI you should have a look at the official documentation pages most notably the modules tutorial and the modules reference. Although this reference is written for OpenWrt most of the facts also apply for the Fon-ng firmware.
You can also find an API documentation of LuCI. An adapted version of this reference featuring the special features of the Fon-ng firmware will be provided in the near future.
LuCI features a special SDK that gives you the ability to develop and test your (web user interface) applications on a common PC running Linux or similar *nixoid operating systems. A copy of this SDK can be found in the Fonosfera SVN.
The LuCI SDK
To use the testing and debugging facilities of the LuCI SDK you need the following programs installed on your computer: GCC, pkg-config, Flex, Bison, Make, wget, Lua 5.1.x + development headers.
By typing make run you get an overview over available testing and debugging targets. Most notably make runttpd starts the embedded webserver which serves the Fon-ng webinterface on http://127.0.0.1:8080/luci/ and make runlua which opens an interactive Lua console.