Developer Notes

LeMock is implemented in Lua 5.1, but its source code is written as literate documents, and usees the tool noweb to generate the .lua files. The distributed source archive includes all the tangled files in the build directory, to avoid dependending on noweb for installation.

The source is contained in the src directory in the form of literate documents. To extract (tangle) the final files from the sources, the tool noweb is needed.

The source files are meant to be tangled together all at once, because the contents of a target file can be spread over several source files. The target files are all the chunk names that are roots. These can be found with noroots in the noweb toolbox. To automate the tangle process, there is a custom script named autotangle in the tools directory. This script finds all the target file names and tangles them in the current directory, creating subdirectories as needed. The script is written for yet another obscure tool, rc [1]. It is probably easy to port the short rc script to your favourit language. It is invoked (in rc syntax) as:

../tools/autotangle `{find ../src -name '*.nw'}

which means it wants all (recursively) .nw files in the src directory as arguments.

The documentation is written in txt2tags, which can generate HTML among many other formats. The README, HISTORY, COPYRIGHT, and this DEVEL text file are written as simple txt2tags documents to remain readable as is. The .nw source files define wrapper txt2tags documents for the web pages, which use txt2tags' include mechanism to include the actual txt2tags files. The user guide is defined in the .nw sources as a separate txt2tags document, so it can be easily generated as a LaTeX document or Unix man page, but it too is included in a wrapper txt2tags document when generating the web pages.

The building of the web pages is done with mk, a Unix port of the Plan9 make tool. (The mk files uses rc syntax.)

A set of unit tests (defined in the .nw source) can be run with lunit with the command:

lunit unit/*.lua

A program like luacov can be used to check the coverage of the unit tests.


I use Byron's Unix port, which syntax is extended and incompatible with the original (and other ports).