Lua bundle for iRex DR800 and DR1000
====================================
Last update: Tue Dec 14 23:39:13 2010


This is a megapackage including Lua interpreter bundled with a lot
of useful modules and bindings compiled for the iRex DR devices, and
some useful and interesting scripts. All in all, it's a complete
development framework to build applications for the iRex DR800 and
DR1000, in 4 MB!!!

Note you need the core base package, version 4, which you can find at
http://www.mobileread.com/forums/showthread.php?p=887725

I've tried to emulate Hansel's incredible Lua port for Iliad [1] [2],
but I've added some new packages. Consult section below to learn about
all the modules included.

Not all of the included packages have been tested so please try and report
any broken module.
By now I'm aware of next non working packages: alien, and vte.

I've included the documentation, examples and tests of all the packages
in the "docs" directory. You should not copy them to the DR device.

[1] https://dev.mobileread.com/trac/luailiad/wiki
[2] http://www.mobileread.com/forums/showthread.php?t=36483


Steps to install:
=================
1. enable SD card folders browsing (advance settings or look for the
   dr.ini file hack in mobileread forum)
2. connect device to your computer using the USB cable
3. create a folder "/Programs" in SD card root if it does not exist yet
4. you need libs core package installed into SD card/Programs/_base
5. copy "_lua" and "Tools" directory there

Now, you should have something like:
    SD card
        /Programs
            _base             (directory)
            _lua              (directory)
            Tools             (directory)
                RunDebug.desktop  (file)
                Icons.desktop     (file)
            ...

Don't copy "docs" folder or any other files to your DR, they are not necessary.


Scripts included
================
There are some scripts included with this package in _lua/scripts directory.
You could use them as examples, but they also have their interest and purpose.

* run_debug.lua
  This application lets run some other programs and get the output. It is
specially useful to execute command line based scripts or to check why some
applications don't start correctly.
It understands some special types of files like lua, python or shell scripts.
Even it can run the proper command if you select a .desktop file!
It can be started from its own .desktop file, no command line needed.

* icons.lua
  A script which generates images for some types of files, updating device
global database so you can see these images when browsing.
It currently supports next file types:
. Programs: parses .desktop files looking for an Icon entry
. FB2 files: extracts cover image if the ebook has one

* gui-icons.lua
  A GUI frontend for icons.lua


Modules included
================

Base
----
* Lua 5.1.4 (Lua itself). http://www.lua.org/

"Lua is a powerful, fast, light-weight, embeddable scripting language.

Lua combines simple procedural syntax with powerful data description constructs
based on associative arrays and extensible semantics. Lua is dynamically typed,
runs by interpreting bytecode for a register-based virtual machine, and has
automatic memory management with incremental garbage collection, making it
ideal for configuration, scripting, and rapid prototyping."

Note: Lua is compiled without readline to avoid dependencies on libraries
that are not available on a standard DR

* LuaFileSystem 1.4.2. http://www.keplerproject.org/luafilesystem/manual.html

LuaFileSystem is a Lua library developed to complement the set of functions
related to file systems offered by the standard Lua distribution.
LuaFileSystem offers a portable way to access the underlying directory
structure and file attributes.

* LuaPosix 5.1.7 (posix functions). http://luaforge.net/projects/luaposix/

Lua binding for the following Posix functions: access, basename, chdir, chmod,
chown, crypt, ctermid, dirname, dir, dup, errno, exec, execp, fdopen, fileno,
files, fork, getcwd, getenv, getgroup, getlogin, getpasswd, getpid, glob,
hostid, kill, link, mkdir, mkfifo, pathconf, pipe, readlink, rmdir, rpoll,
setenv, setpid, sleep, stat, sysconf, times, ttyname, unlink, umask, uname,
utime, wait.

* lxp 1.1 (luaexpat, xml parser). http://www.keplerproject.org/luaexpat/

"LuaExpat is a SAX XML parser based on the Expat library."

* stdlib 16 (standard libraries). http://luaforge.net/projects/stdlib/

Standard Lua libraries.

* penlight 0.8b. http://penlight.luaforge.net/

"Penlight brings together a set of generally useful pure Lua modules,
focussing on input data handling (such as reading configuration files),
functional programming (such as map, reduce, placeholder expressions,etc),
and OS path management.  Much of the functionality is inspired by the Python
standard libraries."

* alien 0.4.1. http://alien.luaforge.net/

"Alien is a Foreign Function Interface (FFI) for Lua. An FFI lets you call
functions in dynamic libraries (.so, .dylib, .dll, etc.) from Lua code without
having to write, compile and link a C binding from the library to Lua.
In other words, it lets you write extensions that call out to native code
using just Lua."

* lpack. http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/install.html

A simple Lua library for packing and unpacking binary data.

* LuaBitOp 1.0.1. http://bitop.luajit.org/

"Lua BitOp is a C extension module for Lua 5.1 which adds bitwise operations
on numbers."

* rings 1.2.2 (multiple lua states). http://www.keplerproject.org/rings/

Rings is a library which provides a way to create new Lua states from within
Lua. It also offers a simple way to communicate between the creator (master)
and the created (slave) states.

* lrandom. http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/

"A library for generating random numbers based on the Mersenne Twister."

* lmd5. http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/

"A message digest library for Lua based on OpenSSL. It supports MD2, MD4, MD5,
SHA1, SHA2, RIPEMD160."

* lbase64. http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/

"A base64 library for Lua."

* date 2.0.1. http://luaforge.net/projects/date/

"Lua Date & Time module for Lua 5.x."

* gzio 0.9. http://luaforge.net/projects/gzio/

"The Lua gzip file I/O module emulates the standard I/O module, but operates
on compressed gzip format files."

* lpeg 0.10. http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html

"LPeg is a new pattern-matching library for Lua, based on Parsing Expression Grammars (PEGs)."

* lualogging 1.1.4. http://www.keplerproject.org/lualogging/

"LuaLogging provides a simple API to use logging features in Lua.
Its design was based on log4j. LuaLogging currently supports, through
the use of appenders, console, file, email, socket and sql outputs."

* luaprofiler 2.0.2. http://luaprofiler.luaforge.net/

"LuaProfiler is a time profiler designed to help finding bottlenecks on your Lua program."

* lpc 1.0.0. http://lua.net-core.org/sputnik.lua?p=Telesto:About

"Lua Process Call. Allows Lua scripts to call external processes while capturing
both their input and output(in contrast to Lua's popen function that can only
capture one or the other)."

* luadaemon 1.0.0. http://lua.net-core.org/sputnik.lua?p=Telesto:About

"Allows Lua scripts to become Unix daemons easily."


Network
-------
* LuaSocket (network support). http://www.tecgraf.puc-rio.br/~diego/professional/luasocket/

"LuaSocket is a Lua extension library that provides support for networking.
Among the support modules, the most commonly used implement the SMTP (sending
e-mails), HTTP (WWW access) and FTP (uploading and downloading files) client
protocols. These provide a very natural and generic interface to the
functionality defined by each protocol. In addition, you will find that the
MIME (common encodings) and URL (anything you could possible want to do with
one)"

* luacurl 1.2.1. http://luaforge.net/projects/luacurl/

Lua binding for libcurl.

* luajson 1.1. http://luaforge.net/projects/luajson/

JSON Parser/Constructor for Lua.

* cgilua 5.1.2. http://keplerproject.org/cgilua

"CGILua is a tool for creating dynamic Web pages and manipulating input data
from Web forms. CGILua allows the separation of logic and data handling from
the generation of pages, making it easy to develop web applications with Lua."

* xavante 2.0.0 (light webserver). http://www.keplerproject.org/xavante/

Xavante is a Lua HTTP 1.1 Web server that uses a modular architecture based
on URI mapped handlers. Xavante currently offers a file handler, a redirect
handler and a WSAPI handler. Those are used for general files, URI remapping
and WSAPI applications respectively.

* copas 1.1.4. http://www.keplerproject.org/copas/

"Copas is a dispatcher based on coroutines that can be used by TCP/IP servers.
It uses LuaSocket as the interface with the TCP/IP stack."

* coxpcal 1.13.0. http://coxpcall.luaforge.net/

"Coxpcall encapsulates the protected calls with a coroutine based loop,
so errors can be dealed without the usual pcall/xpcall issues with coroutines."

* wsapi 1.0.0. http://wsapi.luaforge.net/

"WSAPI is an API that abstracts the web server from Lua web applications.
By coding against WSAPI your application can run on any of the supported
servers and interfaces (currently CGI, FastCGI and Xavante, on Windows and
UNIX-based systems)."

* orbit 2.0.2. http://orbit.luaforge.net/

"Orbit is an MVC web framework for Lua. The design is inspired by lightweight
Ruby frameworks such as Camping. It completely abandons the current CGILua
model of "scripts" in favor of applications, where each Orbit application can
fit in a single file, but you can split it into multiple files if you want."


GUI
---
* lgob 10.11 (Gtk+/GNOME bindings). http://oproj.tuxfamily.org/wiki/doku.php?id=lgob

Complete and superb bindings for everything Gtk+/GNOME.
Included here: gobject, glib, gdk, atk, gtk, pango, cairo, gtksourceview,
               gtkspell, poppler, goocanvas, vte, webkit.

* luaplot 0.2.0. http://oproj.tuxfamily.org/wiki/doku.php?id=luaplot

"luaplot is a plotting library for Lua, based on CairoPlot.
It uses cairo as drawing library (supporting several output formats)
and can be integrated with GTK+."


Extra
-----
* nixio 0.3 (system, networking and I/O library). http://dev.luci.freifunk-halle.net/nixio/doc/

"A well-documented multipurpose Lua library offering system, networking
(IPv4, IPv6 and UNIX), I/O (Files, Pipes, UDP-, TCP-, and TLS-sockets),
byte manipulation, hashing and other useful functionality."

* ldbi 0.3.0 (SQLite bindings). http://oproj.tuxfamily.org/wiki/doku.php?id=ldbi

"ldbi binds popular database engines to Lua. Currently supports PostgreSQL
and SQLite." Only SQLite bindings are included here.

* luadbus 0.0.1. http://luaforge.net/projects/lua-dbus/

"LuaDBUS is a dbus binding intended to provide easy access to the full
facilities offered by the dbus specifications: bus creation and connexion,
message bunding and parsing."

* ldbus. https://github.com/daurnimator/ldbus/

Another Lua Bindings to dbus.

* hpdf 1.0. http://code.google.com/p/luahpdf/

"LuaHPDF is a Lua module that lets you programmatically create PDF
files using Lua. It does this by binding to the Haru Free PDF Library,
an open-source library that manages the details of PDF generation."


Enjoy,
Iñigo Serna
