Installing
Xavante follows the package model for Lua 5.1, therefore it should be "installed". Refer to Compat-5.1 configuration section about how to install the modules properly.
Windows users can use the pre-compiled version of Xavante's binary components (LuaFileSystem and LuaSocket) available at LuaForge.
Xavante installation is very flexible and is based on three directories:
$LIB - Lua binary libraries
$LUA - Lua libraries
$WEB - Xavante HTTP documents.
For convenience, those directories can be under the same home directory as the following examples show.
The Xavante source includes a file t_xavante_start.lua. This is
a template for the Xavante startup file. You must edit it so it reflects your system paths
and then rename it to xavante_start.lua.
Windows Installation Example
An example of a Windows LuaBinaries compatible Xavante installation is the one used by Kepler. It is shown below with the list of included files and where those files can be found in LuaForge.
For each of the projects downloaded from LuaForge, you'll have to copy the source files to the corresponding directory below. Note that sometimes the LuaForge download may include a somewhat different name for the directory.
$HOME
lua50.dll -- LuaBinaries
lua50.exe -- LuaBinaries
xavante_start.lua -- Xavante (t_xavante_start.lua)
$LIB
lfs.dll -- LuaFileSystem
lmime.dll -- LuaSocket
lsocket.dll -- LuaSocket
$LUA
compat-5.1.lua -- Compat
ltn12.lua -- LuaSocket
mime.lua -- LuaSocket
stable.lua -- VEnv
venv.lua -- VEnv
/cgilua -- CGILua
...
/copas -- Copas
...
/coxpcall -- Xavante
coxpcall.lua
/sajax -- Xavante
sajax.lua
/socket -- LuaSocket
...
/xavante -- Xavante
...
$CONF
/cgilua
config.lua -- CGILua
/xavante
config.lua -- Xavante
$WEB
index.lp -- Xavante
test.lp -- Xavante
/doc -- Xavante (doc/us)
...
/img -- Xavante
...
Note that the Kepler installation creates a separate directory for
configuration files ($CONF) and adjusts LUA_PATH
accordingly to make sure that the files present on $CONF
are found first.
The example below shows the startup file xavante_start.lua
for a Kepler Windows installation on c:\kepler.
--- compatibility code for Lua version 5.0 providing 5.1 behavior
if string.find (_VERSION, "Lua 5.0") and not _COMPAT51 then
if not LUA_PATH then
LUA_PATH = "c:/kepler/conf/?.lua;"..
"c:/kepler/lua/?.lua;"..
"c:/kepler/lua/?/?.lua;"..
"c:/kepler/lua/?/init.lua;"
end
require"compat-5.1"
package.cpath = "c:/kepler/lib/?.dll"
end
require "xavante.server"
xavante.setwebdir("c:/kepler/web/")
xavante.start(XAVANTE_ISFINISHED, XAVANTE_TIMEOUT)
Linux Installation Example
And example of a Linux Xavante installation is the one used by Kepler. It puts the
$HOME directory at /usr/local/kepler,
the $LIB directory at /usr/local/lib/lua/5.0,
with a symbolic link at $HOME/lib, the $LUA directory at
/usr/local/share/lua/5.0, with a symbolic link at $HOME/lua.
It also assumes that the Lua executable, the Lua Library and xavante_start.lua
are located in the system path (usually /usr/local/bin).
The Linux Makefile uses sed to build a xavante_start.lua
that conforms to the above Kepler installation directories.
The Linux Xavante installation would differ only in the contents of
the $LIB directories
$HOME
$LIB
lfs.so
lmime.so
lsocket.so
and in the definition of the paths in xavante_start.lua:
--- compatibility code for Lua version 5.0 providing 5.1 behavior
if string.find (_VERSION, "Lua 5.0") and not _COMPAT51 then
if not LUA_PATH then
LUA_PATH = "/usr/local/kepler/conf/?.lua;"..
"/usr/local/share/lua/5.0/?.lua;"..
"/usr/local/share/lua/5.0/?/?.lua;"..
"/usr/local/share/lua/5.0/?/init.lua;"
end
require"compat-5.1"
package.cpath = "/usr/local/lib/lua/5.0/?.so"
end
require "xavante.server"
xavante.setwebdir("/usr/local/kepler/web/")
xavante.start(XAVANTE_ISFINISHED, XAVANTE_TIMEOUT)
To install Xavante from the distribution source in a Linux enviroment, simply
edit the config file to use the correct paths for your system and do:
make make install
Configuring
The file $LUA/xavante/config.lua defines the
Xavante configuration. On the Kepler example, this file is copied to the
$CONF/xavante directory to make it easier to upgrade
a Xavante installation since the searching order of
LUA_PATH will make the command
require"xavante.config" find the
$CONF/xavante/config.lua before the
$LUA/xavante/config.lua.
Xavante defines virtualhosts for each site that it is running. Each virtualhost can define a set of rules for it. Each rule matches a URL pattern with a handler. Xavante currently offers a file handler, a redirect handler and a CGILua handler for general files, URL remapping and CGILua scripts respectively.
A typical config.lua uses the format below
require "xavante.filehandler"
require "xavante.cgiluahandler"
require "xavante.redirecthandler"
local simplerules = {
-- URL remapping example
{match = "/", with = xavante.redirecthandler,
params = {"index.lp"}},
-- filehandler example
{match = "/*", with = xavante.filehandler,
params = {baseDir = xavante.webdir()}},
-- cgiluahandler example
{match = {"/*.lp", "/*.lua"},
with = xavante.cgiluahandler.makeHandler (xavante.webdir())},
}
xavante.HTTP{
server = {host = "*", port = 80},
defaultHost = {
rules = simplerules
},
}
To use virtual hosts with Xavante, the call to xavante.HTTP
would be changed to something like
xavante.HTTP{
server = {host = "*", port = 80},
defaultHost = {},
virtualhosts = {
["www.sitename.com"] = simplerules
}
}
Running
Running Xavante requires the execution of the correctly set
xavante_start.lua. This can be done through a
.bat file in Windows, or by giving execution rights to
the xavante_start.lua on Linux.
The example below is a xavante.bat that can be used to start
Xavante in Windows using the same configuration as the above examples.
@echo Xavante Started @c:\kepler\lua50.exe c:\kepler\xavante_start.lua
Remember that xavante_start.lua is the configured version of
t_xavante_start.lua and if you are
installing Xavante from the source
files you should edit it first.
After Xavante is started, opening the URL
http://localhost on your browser should show the Xavante welcome page.
If you changed the port number on config.lua you should also use this
port number in the URL.
The welcome page presents the Xavante version and links to the documentation and for a simple set of tests.