1 files changed, 79 insertions, 0 deletions
diff --git a/extras/luacov/README.md b/extras/luacov/README.md
new file mode 100644
index 0000000..efc31c5
--- /dev/null
+++ b/extras/luacov/README.md
@@ -0,0 +1,79 @@
+## Overview
+
+LuaCov is a simple coverage analyzer for [Lua](http://www.lua.org)
+scripts. When a Lua script is run with the `luacov` module loaded, it
+generates a stats file with the number of executions of each line of the
+script and its loaded modules. The `luacov` command-line script then
+processes this file generating a report file which allows one to visualize
+which code paths were not traversed, which is useful for verifying the
+effectiveness of a test suite.
+
+LuaCov is free software and, like Lua, is released under the
+[MIT License](http://www.lua.org/license.html).
+
+## Download and Installation
+
+LuaCov can be downloaded from its
+[LuaForge page](http://luaforge.net/projects/luacov/files).
+
+It can also be installed using Luarocks:
+
+    luarocks install luacov
+
+LuaCov is written in pure Lua and has no external dependencies.
+
+## Instructions
+
+Using LuaCov consists of two steps: running your script to collect
+coverage data, and then running `luacov` on the collected data to
+generate a report.
+
+To collect coverage data, your script needs to load the `luacov`
+Lua module. This can be done from the command-line, without modifying
+your script, like this:
+
+    lua -lluacov test.lua
+
+Alternatively, you can add `require("luacov")` to the first line
+of your script.
+
+Once the script is run, a file called `lcov.stats.out` is generated.
+If the file already exists, statistics are _added_ to it. This is useful,
+for example, for making a series of runs with different input parameters in
+a test suite. To start the accounting from scratch, just delete the stats file.
+
+To generate a report, just run the `luacov` command-line script.
+It expects to find a file named `lcov.stats.out` in the current
+directory, and outputs a file named `lcov.report.out`.
+
+This is an example output of the report file:
+
+    ============================================================
+    ../test.lua
+    ============================================================
+
+            -- Which branch will run?
+    1       if 10 > 100 then
+    0          print("I don't think this line will execute.")
+    0       else
+    1          print("Hello, LuaCov!")
+    1       end
+
+Note that to generate this report, `luacov` reads the source files.
+Therefore, it expects to find them in the same location they were when
+the `luacov` module ran (the stats file stores the filenames, but
+not the sources themselves).
+
+LuaCov saves its stats upon normal program termination. If your program
+is a daemon -- in other words, if it does not terminate normally -- you
+can use the `luacov.tick` module, which periodically saves the
+stats file. For example, to run (on Unix systems) LuaCov on
+[Xavante](http://www.keplerproject.org/xavante),
+just modify the first line of `xavante_start.lua` so it reads:
+
+    #!/usr/bin/env lua -lluacov.tick
+
+## Credits
+
+LuaCov was designed and implemented by Hisham Muhammad as a tool for
+testing [Luarocks](http://luarocks.luaforge.net).