From e0fde57e050da8ae29bf1a95aee958dfff2510e2 Mon Sep 17 00:00:00 2001 From: oetiker Date: Mon, 6 Oct 2008 05:05:19 +0000 Subject: [PATCH] Support to Lua 5.0 -- Fidelis Assis git-svn-id: svn://svn.oetiker.ch/rrdtool/trunk/program@1579 a5681a0c-68f1-0310-ab6d-d61299d08faa --- CONTRIBUTORS | 1 + bindings/Makefile.am | 2 +- bindings/lua/Makefile.lua | 176 ++++++++++++++++++++++---------------------- bindings/lua/README | 72 +++++++++++++++--- bindings/lua/rrdlua.c | 13 ++++ configure.ac | 169 +++++++++++++++++++++++++++++++++--------- doc/rrdlua.pod | 183 +++++++++++++++++++++++++++++++--------------- 7 files changed, 425 insertions(+), 191 deletions(-) diff --git a/CONTRIBUTORS b/CONTRIBUTORS index ebb76e3..8c3e4be 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -22,6 +22,7 @@ David L. Barker xport function bug fixes Evan Miller Multiplicative HW Enhancements Frank Strauss TCL bindings Florian octo Forster rrd_restore libxml2 rewrite, deprecated function export, rrdcached +Fidelis Assis lua bindings Henrik Storner functions for min/max values of data in graph Hermann Hueni (SunOS porting) Jakob Ilves HPUX 11 diff --git a/bindings/Makefile.am b/bindings/Makefile.am index fd0a352..f6c8d98 100644 --- a/bindings/Makefile.am +++ b/bindings/Makefile.am @@ -35,7 +35,7 @@ python: cd python && env BUILDLIBDIR=../../src/.libs $(PYTHON) setup.py build_ext --rpath=$(libdir) && env LIBDIR=../../src/.libs $(PYTHON) setup.py build lua: - cd lua && $(LUA) Makefile.lua "PREFIX=$(prefix) POD2MAN=$(POD2MAN) LUABIN=$(LUA) $(LUA_MAKE_OPTIONS)" > Makefile && $(MAKE) + cd lua && $(LUA) Makefile.lua > Makefile && $(MAKE) # rules for building the perl module perl_piped: perl-piped/Makefile diff --git a/bindings/lua/Makefile.lua b/bindings/lua/Makefile.lua index 08be1cc..6d68cea 100644 --- a/bindings/lua/Makefile.lua +++ b/bindings/lua/Makefile.lua @@ -1,82 +1,47 @@ --- min version -local min_major, min_minor = 5, 1 -local major, minor = string.match(_VERSION, 'Lua (%d+)\.(%d*)') - -if (tonumber(major) < min_major or - tonumber(major) == min_major and tonumber(minor) < min_minor) then - error(string.format( - '\n\n*** Lua rrdtool module requires Lua %d.%d or greater. ***\n', - min_major, min_minor)) - os.exit(1) -end -local lua_version = major .. '.' .. minor -local options = arg[1] -if options then - io.write(string.gsub(options, ' (%S-=)', '\n%1'), '\n\n') +print(string.format('%s %s %s\n', '# Makefile generated by', _VERSION, 'from Makefile.lua.\n')) + +local opts = { + LUA = '/usr/bin/lua', + LUA_MAJOR = '5', + LUA_MINOR = '0', + LUA_HAVE_COMPAT51 = 'HAVE_COMPAT51', + LUA_RRD_LANGPREF = '/scratch/rrd4/lib/lua', + LUA_CFLAGS = '-I/usr/include//lua50 ', + LUA_LFLAGS = '-llualib50 -llua50 ', + LUA_SRCS = 'rrdlua.c', + LUA_OBJS = 'rrdlua.o', + LUA_INSTALL_CMOD = '/scratch/rrd4/lib/lua/5.0', + CC = 'gcc', +} + +-- doesn't preserve key order, but it's OK +for k, v in pairs(opts) do + print(string.format('%s=%s', k, v)) end -io.stdout:write([[ -T= rrd -# Version -LIB_VERSION=0.0.8 -LUA_VERSION=]],major, '.',minor,[[ - - -# set lua include, lib and C installation dirs -PKG_CONFIG=$(firstword $(shell which pkg-config)) -ifeq (pkg-config,$(findstring pkg-config,$(PKG_CONFIG))) - LUA_LIBDIR=$(shell pkg-config --variable=INSTALL_CMOD lua$(LUA_VERSION)) - ifeq (,$(LUA_LIBDIR)) - $(warning *** couldn't find lua$(LUA_VERSION).pc) - else - LUA_CFLAGS=$(shell pkg-config --cflags lua$(LUA_VERSION) 2>/dev/null) - LUA_LFLAGS=$(shell pkg-config --libs lua$(LUA_VERSION) 2>/dev/null) - endif -else - $(warning couldn't find pkg-config) -endif - -ifeq (,$(LUA_LIBDIR)) - $(warning *** setting Lua dirs to defaults in src package) - LUA_CFLAGS=-I/usr/local/include -I/usr/local/include/lua - LUA_LFLAGS=-L/usr/local/lib/lua/$(LUA_VERSION) -llua - LUA_LIBDIR=/usr/local/lib/lua/$(LUA_VERSION) -endif - -]]) +local lua_ver = opts['LUA_MAJOR'] .. '.' .. opts['LUA_MINOR'] --- overwrite global LUA_LIBDIR if default lib is set -if lib then - io.stdout:write([[ -# override LUA_LIBDIR for site install -LUA_LIBDIR=]],lib,[[/$(LUA_VERSION) -]]) -end +print([[ -io.stdout:write([[ +T= rrd +# Version +LIB_VERSION=0.0.9 # OS dependent LIB_EXT= .so -# if this "autoconf" doesn't work for you, set LIB_OPTION for shared -# object manually. -LD=$(shell ld -V -o /dev/null 2>&1) -ifneq (,$(findstring Solaris,$(LD))) - # Solaris - tested with 2.6, gcc 2.95.3 20010315 and Solaris ld - LIB_OPTION= -G -dy -else - ifneq (,$(findstring GNU,$(LD))) - # GNU ld - LIB_OPTION= -shared -dy - else - $(error couldn't identify your ld. Please set the shared option manually) - endif -endif - -RRD_CFLAGS=-I../../src/ +LIBNAME= $T-$(LIB_VERSION)$(LIB_EXT) + +RRD_CFLAGS=-I../../src RRD_LIB_DIR=-L../../src/.libs -lrrd +# Set shared object options to what your platform requires +# For Solaris - tested with 2.6, gcc 2.95.3 20010315 and Solaris ld: +# LIB_OPTION= -G -dy +# For GNU ld: +LIB_OPTION= -shared -dy + # Choose the PIC option # safest, works on most systems PIC=-fPIC @@ -84,15 +49,9 @@ PIC=-fPIC #PIC=-fpic # Compilation directives -OPTIONS= -O3 -Wall ${PIC} -fomit-frame-pointer -pedantic-errors -W -Waggregate-return -Wcast-align -Wmissing-prototypes -Wnested-externs -Wshadow -Wwrite-strings +OPTIONS= -O3 -Wall $(PIC) -fomit-frame-pointer -pedantic-errors -W -Waggregate-return -Wcast-align -Wmissing-prototypes -Wnested-externs -Wshadow -Wwrite-strings LIBS= $(RRD_LIB_DIR) $(LUA_LFLAGS) -lm -CFLAGS= $(OPTIONS) $(LUA_CFLAGS) $(RRD_CFLAGS) -DLIB_VERSION=\"$(LIB_VERSION)\" -#CC= gcc - -LIBNAME= $T-$(LIB_VERSION)$(LIB_EXT) - -SRCS= rrdlua.c -OBJS= rrdlua.o +CFLAGS= $(OPTIONS) $(LUA_CFLAGS) $(RRD_CFLAGS) -DLIB_VERSION=\"$(LIB_VERSION)\" -DLUA$(LUA_MAJOR)$(LUA_MINOR) -D$(LUA_HAVE_COMPAT51) all: $(LIBNAME) @@ -100,21 +59,64 @@ lib: $(LIBNAME) *.o: *.c -$(LIBNAME): $(OBJS) - $(CC) $(CFLAGS) $(LIB_OPTION) $(OBJS) $(LIBS) -o $(LIBNAME) +$(LIBNAME): $(LUA_OBJS) + $(CC) $(CFLAGS) $(LIB_OPTION) $(LUA_OBJS) $(LIBS) -o $(LIBNAME) install: $(LIBNAME) - mkdir -p $(LUA_LIBDIR) - cp $(LIBNAME) $(LUA_LIBDIR) - strip $(LUA_LIBDIR)/$(LIBNAME) - (cd $(LUA_LIBDIR) ; rm -f $T$(LIB_EXT) ; ln -fs $(LIBNAME) $T$(LIB_EXT)) - $(POD2MAN) --release=$(VERSION) --center=RRDLua --section=3 rrdlua.pod > $(PREFIX)/man/man3/rrdlua.3 + mkdir -p $(LUA_INSTALL_CMOD) + cp $(LIBNAME) $(LUA_INSTALL_CMOD) + #strip $(LUA_INSTALL_CMOD)/$(LIBNAME) + (cd $(LUA_INSTALL_CMOD) ; rm -f $T$(LIB_EXT) ; ln -fs $(LIBNAME) $T$(LIB_EXT))]]) +if lua_ver == '5.0' and opts['LUA_HAVE_COMPAT51'] ~= 'HAVE_COMPAT51' then + print([[ + mkdir -p $(LUA_RRD_LANGPREF)/5.0 + cp compat-5.1r5/compat-5.1.lua $(LUA_RRD_LANGPREF)/5.0 +]]) +end + +print([[ + +test.lua: $(LIBNAME) test.lua.bottom + @echo "-- Created by Makefile." > test.lua + @echo "-- Test script adapted from the one in the Ruby binding." > test.lua + @echo >> test.lua]]) +if lua_ver == '5.0' then + print([[ + @echo "--- compat-5.1.lua is only required for Lua 5.0 ----------" >> test.lua]]) + + if opts['LUA_HAVE_COMPAT51'] ~= 'HAVE_COMPAT51' then + print([[ + @echo "original_LUA_PATH = LUA_PATH" >> test.lua + @echo "-- try only compat-5.1.lua installed with RRDtool package" >> test.lua + @echo "LUA_PATH = '$(LUA_RRD_LANGPREF)/5.0/?.lua'" >> test.lua]]) + end + print([[ + @echo "local r = pcall(require, 'compat-5.1')" >> test.lua + @echo "if not r then" >> test.lua + @echo " print('** compat-5.1.lua not found')" >> test.lua + @echo " os.exit(1)" >> test.lua + @echo "end" >> test.lua]]) + + if opts['LUA_HAVE_COMPAT51'] ~= 'HAVE_COMPAT51' then + print([[ + @echo "LUA_PATH = original_LUA_PATH" >> test.lua + @echo "original_LUA_PATH = nil" >> test.lua]]) + end + print([[ + @echo "----------------------------------------------------------" >> test.lua + @echo >> test.lua]]) +end +if opts['LUA_RRD_LANGPREF'] .. '/' .. lua_ver == opts['LUA_INSTALL_CMOD'] then + print([[ + @echo "package.cpath = '$(LUA_INSTALL_CMOD)/?.so;' .. package.cpath" >> test.lua]]) +end +print([[ + @cat test.lua.bottom >> test.lua -test: $(LIBNAME) - ln -sf $(LIBNAME) rrd.so - lua test.lua +test: test.lua + $(LUA) test.lua clean: - rm -f $L $(LIBNAME) $(OBJS) *.so *.rrd *.xml *.png *~ + rm -f $(LIBNAME) $(LUA_OBJS) test.lua *.so *.rrd *.xml *.png *~ ]]) diff --git a/bindings/lua/README b/bindings/lua/README index f1fe186..0eaaccc 100644 --- a/bindings/lua/README +++ b/bindings/lua/README @@ -1,21 +1,69 @@ RRDLua is a Lua module for RRD functions. -Compiling: +- Configuration -Just run "configure" from the top RRDTool package dir and then 'make'. -You should have lua and lua-dev packages installed before executing -configure. + From the top dir of RRDtool package, run "./configure", or + "./configure --enable-lua-site-install" if you prefer to install it + in Lua's search path. -Testing: + You should have lua and lua-dev packages installed before executing + configure. -Enter the bindings/lua dir, run 'make test' and use your preferred -viewer to display the just created graph 'test.png'. If you can read -"Enjoy Lua RRDtool module!" on the picture, everything went fine. +- Compilation and installation -Installation: + Run 'make' and 'sudo make install'. If you don't enable lua-site-install, + the Lua module will be installed together with RRDtool, under the subdir + lib/lua/. -Run 'make install' from the top dir of the RRDtool package. The Lua -module will be installed in the same RRDtool installation dir, -under the subdir lib/lua/. +- Testing + Install RRDtool first, as above. Then, enter the bindings/lua dir, run + 'make test' and use your preferred viewer to display the just created + 'test.png'. If you can read "Enjoy Lua RRDtool module!" on the picture, + everything went fine. + +- Using with Lua 5.1 + + Start your programs with: + + --------------------------------------------------------------- + package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' .. + package.cpath + require 'rrd' + --------------------------------------------------------------- + + OBS: If you use the option --enable-lua-site-install you won't need + to change package.cpath like above. + +- Using with Lua 5.0 + + The Lua binding for RRDtool needs the compat-5.1 module to work with + Lua 5.0. Some Linux distros, like Ubuntu gutsy and hardy, have it + already integrated in Lua 5.0 -dev packages, so you just have to + require: + + require 'compat-5.1' + + For other platforms, the compat-5.1 module that comes with this Lua + binding will be installed for you in the same dir where RRDtool was + installed, under the subdir .../lib/lua/5.0. In this case, you must + tell your Lua programs where to find it by changing the Lua var + LUA_PATH: + + --- compat-5.1.lua is only necessary for Lua 5.0 ---------------- + original_LUA_PATH = LUA_PATH + -- try only compat-5.1 installed with RRDtool package + LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua' + require 'compat-5.1' + LUA_PATH = original_LUA_PATH + original_LUA_PATH = nil + --- end of code to require compat-5.1 --------------------------- + + Now we can require the rrd module in the same way we did for 5.1 above: + + --------------------------------------------------------------- + package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' .. + package.cpath + require 'rrd' + --------------------------------------------------------------- diff --git a/bindings/lua/rrdlua.c b/bindings/lua/rrdlua.c index a786077..bef3e66 100644 --- a/bindings/lua/rrdlua.c +++ b/bindings/lua/rrdlua.c @@ -26,6 +26,14 @@ #include "lualib.h" #include "../../src/rrd_tool.h" +#ifdef LUA50 + #ifdef HAVE_COMPAT51 + #include "compat-5.1.h" + #else + #include "compat-5.1r5/compat-5.1.h" + #endif +#endif + extern void rrd_freemem(void *mem); extern int luaopen_rrd (lua_State * L); @@ -354,7 +362,12 @@ static const struct luaL_reg rrd[] = { int luaopen_rrd (lua_State * L) { +#if defined LUA50 + /* luaL_module is defined in compat-5.1.c */ + luaL_module (L, "rrd", rrd, 0); +#else luaL_register (L, "rrd", rrd); +#endif set_info (L); return 1; } diff --git a/configure.ac b/configure.ac index 3dcc155..a2ece2b 100644 --- a/configure.ac +++ b/configure.ac @@ -636,45 +636,146 @@ AC_SUBST(COMP_RUBY) dnl Check for Lua. AC_PATH_PROG(LUA, lua, no) -AC_ARG_ENABLE(lua,[ --disable-lua do not build the lua modules], +AC_ARG_ENABLE(lua,[ --disable-lua do not build the lua modules], [],[enable_lua=yes]) -AC_MSG_CHECKING(if lua modules can be built) - COMP_LUA= -if test "x$LUA" = "xno" -o x$enable_lua = xno; then - AC_MSG_RESULT(No .. Lua not found or disabled) +if test "$LUA" = "no" -o "$enable_lua" = "no"; then + enable_lua=no else - for dir in /usr/include/lua /usr/include/lua5.1 /usr/local/include/lua5.1 /usr/include/lua5.2 /usr/local/include/lua5.2 ; do - if test -f "$dir/lualib.h" ; then - enable_lua=yes - COMP_LUA="lua" - break + AC_MSG_CHECKING(for lua >= 5.0) + read LUA_MAJOR LUA_MINOR LUA_POINT <&1 | cut -f2 -d' ' | sed -e 's/\./ /g') +LUA_EOF + if test 0$LUA_MAJOR -lt 5; then + AC_MSG_RESULT([no, version found is $LUA_MAJOR.$LUA_MINOR]) + else + AC_MSG_RESULT([$LUA_MAJOR.$LUA_MINOR found]) + vdot=$LUA_MAJOR.$LUA_MINOR + vndot=$LUA_MAJOR$LUA_MINOR + lua_version=$LUA_MAJOR.$LUA_MINOR.$LUA_POINT + AC_CHECK_HEADERS(lua$vndot/lua.h, + [AC_CHECK_HEADERS(lua$vndot/lualib.h, + [AC_CHECK_HEADER(lua$vndot/lauxlib.h, + [lua_headerdir=lua$vndot], + [])], + [])], + [AC_CHECK_HEADERS(lua$vdot/lua.h, + [AC_CHECK_HEADERS(lua$vdot/lualib.h, + [AC_CHECK_HEADER(lua$vdot/lauxlib.h, + [lua_headerdir=lua$vdot], + [])], + [])], + [AC_CHECK_HEADERS(lua.h, + [AC_CHECK_HEADERS(lualib.h, + [AC_CHECK_HEADER(lauxlib.h, + [lua_headerdir=""], + [lua_headerdir="no"])], + [])], + [])])]) + + if test "$lua_headerdir" = "no"; then + enable_lua=no + else + COMP_LUA=lua fi - done - if test "$COMP_LUA" = "lua" ; then - AC_MSG_RESULT(YES) - else - AC_MSG_RESULT(Lua found but lualib.h is missing! Install the -dev package) - fi -fi + if test "$COMP_LUA" != "lua"; then + enable_lua=no + AC_MSG_WARN([Lua $vdot found but not lua.h, lualib.h and lauxlib.h! Please install the -dev packages for Lua $vdot]) + else + # OK, headers found, let's check the libraries (LIBS is not used) + LIBS= + lua_havelib=no + LUA_HAVE_COMPAT51=DONT_HAVE_COMPAT51 + AC_SEARCH_LIBS(lua_call, lua$vdot lua$vndot lua, + [AC_SEARCH_LIBS(luaL_register, lua$vdot lua$vndot lua, + [lua_havelib=LUA$vndot], + [AC_SEARCH_LIBS(luaL_module, lualib$vndot lualib$vdot lualib, + [lua_havelib=$vndot ; + AC_CHECK_HEADERS(lua$vndot/compat-5.1.h, + [LUA_HAVE_COMPAT51=HAVE_COMPAT51], [], + [[#include + #include ]])], + [AC_SEARCH_LIBS(luaL_openlib, lualib$vdot lualib$vndot lualib, + [lua_havelib=$vndot], + [COMP_LUA=], [-lm])], [-lm])], [-lm])], + [COMP_LUA=], [-lm]) + lua_libs=$LIBS + LIBS= + + # Options to pass when configuring Lua module + if test "$lua_havelib" != "no"; then + # OK, headers and libs found + # try to set lua include, lib and C installation dirs with pkg-config + if test "$PKGCONFIG" != "no"; then + if test "$vndot" = "50"; then + lua_pkg_prefix=lualib + else + lua_pkg_prefix=lua + fi + # try with dot, without dot and finally without version + for f in $lua_pkg_prefix$vdot $lua_pkg_prefix$vndot $lua_pkg_prefix; do + lua_cflags=$($PKGCONFIG --cflags $f 2>/dev/null) + if test "$lua_cflags" != ""; then + # OK, found CFLAGS. Get Lua LFLAGS and lib install dir + LUA_CFLAGS=$lua_cflags + LUA_LFLAGS=$($PKGCONFIG --libs $f) + LUA_INSTALL_CMOD=$($PKGCONFIG --variable=INSTALL_CMOD $f) + break + fi + done + fi -dnl pass additional lua options -# if lua-site-install is set, don't set 'LIB' and let Lua setup decide -# the best place. -AC_ARG_ENABLE(lua-site-install, -[ --enable-lua-site-install by default the rrdtool lua modules are installed - together with rrdtool in $prefix/lib/lua. You have to - add $prefix/lib/lua/$lua_version/?.so to package.cpath - for lua to find the rrd.so file.]. When you set this - option the Lua module will get installed wherever - your Lua setup thinks it is best.], -[LUA_MAKE_OPTIONS=],[LUA_MAKE_OPTIONS="LIB=$langpref/lib/lua"]) + # if not set with pkg-config, use default values in src package + if test "$LUA_CFLAGS" = ""; then + AC_MSG_WARN(Setting Lua include and lib dirs to defaults in src package) + LUA_CFLAGS="-I/usr/local/include -I/usr/local/include/lua -I/usr/local/include/lua/$vdot" + LUA_LFLAGS="-L/usr/local/lib -L/usr/local/lib/lua -L/usr/local/lib/lua/$vdot $lua_libs" + LUA_INSTALL_CMOD="/usr/local/lib/lua/$vdot" + fi + LUA_SRCS=rrdlua.c + LUA_OBJS=rrdlua.o + # If Lua 5.0, we need compat-5.1. Add ours unless already + # integrated as in Debian/Ubuntu 5.0 -dev packages. + if test "$vdot" = "5.0" -a "$LUA_HAVE_COMPAT51" != "HAVE_COMPAT51"; then + LUA_SRCS="rrdlua.c compat-5.1r5/compat-5.1.c" + LUA_OBJS="rrdlua.o compat-5.1r5/compat-5.1.o" + fi -AC_SUBST(LUA_MAKE_OPTIONS) -AC_SUBST(LUA) -AC_SUBST(COMP_LUA) + dnl pass additional lua options + # if lua-site-install is not set, overwrite LUA_INSTALL_CMOD already + # found and install together with RRDtool, under $langpref. + LUA_RRD_LANGPREF="$langpref/lib/lua" + AC_ARG_ENABLE(lua-site-install, + [ --enable-lua-site-install by default the rrdtool lua modules are installed + together with rrdtool in $prefix/lib/lua. You have to + add $prefix/lib/lua/$lua_version/?.so to package.cpath + for lua to find the rrd.so file. When you set this + option the Lua module will get installed wherever + your Lua setup thinks it is best.], + [], + [LUA_INSTALL_CMOD="$LUA_RRD_LANGPREF/$vdot"]) + + AC_SUBST(LUA) + AC_SUBST(COMP_LUA) + AC_SUBST(LUA_MAJOR) + AC_SUBST(LUA_MINOR) + AC_SUBST(LUA_POINT) + AC_SUBST(LUA_RRD_LANGPREF) + AC_SUBST(LUA_INSTALL_CMOD) + AC_SUBST(LUA_HAVE_COMPAT51) + AC_SUBST(LUA_CFLAGS) + AC_SUBST(LUA_LFLAGS) + AC_SUBST(LUA_SRCS) + AC_SUBST(LUA_OBJS) + else + enable_lua=no + AC_MSG_RESULT([Lua headers found but not the libraries! Please reinstall the dev packages for Lua $LUA_MAJOR.$LUA_MINOR]) + fi + fi + fi +fi enable_tcl_site=no @@ -773,6 +874,7 @@ AC_CONFIG_FILES([bindings/Makefile]) AC_CONFIG_FILES([bindings/tcl/Makefile]) AC_CONFIG_FILES([bindings/tcl/ifOctets.tcl]) AC_CONFIG_FILES([Makefile]) +AC_CONFIG_FILES([bindings/lua/Makefile.lua]) AC_CONFIG_COMMANDS([default],[[ chmod +x examples/*.pl]],[[]]) AC_OUTPUT @@ -805,9 +907,10 @@ echo " Perl Options: $PERL_MAKE_OPTIONS" echo " Ruby Modules: $COMP_RUBY" echo " Ruby Binary: $RUBY" echo " Ruby Options: $RUBY_MAKE_OPTIONS" -echo " Lua Modules: $COMP_LUA" +echo " Build Lua Bindings: $enable_lua" echo " Lua Binary: $LUA" -echo " Lua Options: $LUA_MAKE_OPTIONS" +echo " Lua Version: $lua_version" +echo " Lua module dir: $LUA_INSTALL_CMOD" echo " Build Tcl Bindings: $enable_tcl" echo " Build Python Bindings: $enable_python" echo " Build rrdcgi: $enable_rrdcgi" diff --git a/doc/rrdlua.pod b/doc/rrdlua.pod index a6240f2..7d234fe 100644 --- a/doc/rrdlua.pod +++ b/doc/rrdlua.pod @@ -27,43 +27,104 @@ This module accesses RRDtool functionality directly from within Lua. The arguments to the functions listed in the SYNOPSIS are explained in the regular RRDtool documentation. The command-line call - rrdtool update mydemo.rrd --template in:out N:12:13 + rrdtool update mydemo.rrd --template in:out N:12:13 gets turned into - rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13") - -Note that - - --template=in:out is also valid. + rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13") + +Note that --template=in:out is also valid. + +=head2 Using with Lua 5.1 + +Start your programs with: + + --------------------------------------------------------------- + package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' .. + package.cpath + require 'rrd' + --------------------------------------------------------------- + +OBS: If you configured with --enable-lua-site-install, you don't need +to set package.cpath like above. + +=head2 Using with Lua 5.0 + +The Lua binding for RRDtool needs the Lua module compat-5.1 to work with +Lua 5.0. Some Linux distros, like Ubuntu gutsy and hardy, have it already +integrated in Lua 5.0 -dev packages, so you just have to require it: + + require 'compat-5.1' + +For other platforms, the compat-5.1 module that comes with this binding +will be installed for you in the same dir where RRDtool was installed, +under the subdir .../lib/lua/5.0. In this case, you must tell your Lua +programs where to find it by changing the Lua var LUA_PATH: + + -- compat-5.1.lua is only necessary for Lua 5.0 ---------------- + -- try only compat-5.1 installed with RRDtool package + local original_LUA_PATH = LUA_PATH + LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua' + require 'compat-5.1' + LUA_PATH = original_LUA_PATH + original_LUA_PATH = nil + --- end of code to require compat-5.1 --------------------------- + + Now we can require the rrd module in the same way we did for 5.1 above: + + --------------------------------------------------------------- + package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' .. + package.cpath + require 'rrd' + --------------------------------------------------------------- =head2 Error Handling The Lua RRDTool module functions will abort your program with a stack traceback when they can not make sense out of the arguments you fed them. - - Ex: - - -- If the Lua RRDTool module was installed together with RRDTool, - -- in $prefix/lib/lua/$lua_version, package.cpath must be set like - -- in the example below, so that 'require' can find the module: - - package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.so;' .. - package.cpath - local rrd = require 'rrd' - rrd.update ("mydemo.rrd","N:12:13") - - $ lua t.lua - - lua: t.lua:8: opening 'mydemo.rrd': No such file or directory - stack traceback: - [C]: in function 'update' - t.lua:8: in main chunk - [C]: ? - -You may capture and handle the errors yourself, instead of just letting -the program abort, by calling the module functions through Lua protected -calls - 'pcall' or 'xpcall'. +However, you can capture and handle the errors yourself, instead of just +letting the program abort, by calling the module functions through Lua +protected calls - 'pcall' or 'xpcall'. + + Ex: program t.lua + + --- compat-5.1.lua is only necessary for Lua 5.0 ---------------- + -- uncomment below if your distro has not compat-5.1 + -- original_LUA_PATH = LUA_PATH + -- try only compat-5.1.lua installed with RRDtool package + -- LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua' + + -- here we use a protected call to require compat-5.1 + local r = pcall(require, 'compat-5.1') + if not r then + print('** could not load compat-5.1.lua') + os.exit(1) + end + + -- uncomment below if your distro has not compat-5.1 + -- LUA_PATH = original_LUA_PATH + -- original_LUA_PATH = nil + --- end of code to require compat-5.1 --------------------------- + + -- If the Lua RRDTool module was installed together with RRDTool, + -- in /usr/local/rrdtool-1.3.2/lib/lua/5.0, package.cpath must be + -- set accordingly so that 'require' can find the module: + + package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' .. + package.cpath + + local rrd = require 'rrd' + rrd.update ("mydemo.rrd","N:12:13") + +If we execute the program above we'll get: + + $ lua t.lua + + lua: t.lua:27: opening 'mydemo.rrd': No such file or directory + stack traceback: + [C]: in function `update' + t.lua:27: in main chunk + [C]: ? =head2 Return Values @@ -74,26 +135,26 @@ B returns a single INTEGER representing the timestamp of the first data sample in an RRA within an RRD file. Example returning the first timestamp of the third RRA (index 2): - local firstdate = rrd.first('example.rrd', '--rraindex', 2) + local firstdate = rrd.first('example.rrd', '--rraindex', 2) B returns a single INTEGER representing the last update time. - local lastupdate = rrd.last('example.rrd') + local lastupdate = rrd.last('example.rrd') B returns the x-size and y-size of the created image and a table with the results of the PRINT arguments. - local xsize, ysize, averages = rrd.graph ... - print(string.format("Image size: %dx%d", xsize, ysize) - print("Averages: ", table.concat(averages, ', ')) + local xsize, ysize, averages = rrd.graph ... + print(string.format("Image size: %dx%d", xsize, ysize) + print("Averages: ", table.concat(averages, ', ')) B returns a table where the keys and the values represent property names and property values of the RRD. - local info = rrd.info("test.rrd") - for key, value in pairs(info) do - print(key, ' = ', value) - end + local info = rrd.info("test.rrd") + for key, value in pairs(info) do + print(key, ' = ', value) + end B takes the same parameters as rrd.graph but it returns a table only. The table returned contains meta information about the graph, like @@ -111,27 +172,33 @@ returns 5 values: the initial timestamp, the step, two parallel arrays containing the data source names and their data points respectively, and the final timestamp. - package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.so;' .. - package.cpath - local rrd = require "rrd" - local first, last = rrd.first("test.rrd"), rrd.last("test.rrd") - local start, step, names, data = - rrd.fetch("test.rrd", "--start", first, "--end", last, "AVERAGE") - io.write(string.format("Start: %s (%d)\n", - os.date("%c", start),start)) - io.write("Step size: ", step, " seconds\n") - io.write("DS names: ", table.concat(names, ', '), "\n") - io.write("Data points: ", #data[1], "\n") - io.write("Data:\n") - for i,dp in ipairs(data) do - io.write(os.date("%t", start), " (", start, "): ") - start = start + step - for j,v in ipairs(dp) do - io.write(v, " ") - end - io.write("\n") - end + --require compat-5.1 if necessary + + package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' .. + package.cpath + + local rrd = require "rrd" + local first, last = rrd.first("test.rrd"), rrd.last("test.rrd") + local start, step, names, data = + rrd.fetch("test.rrd", "--start", first, "--end", last, "AVERAGE") + io.write(string.format("Start: %s (%d)\n", + os.date("%c", start),start)) + io.write("Step size: ", step, " seconds\n") + io.write("DS names: ", table.concat(names, ', '), "\n") + io.write("Data points: ", #data[1], "\n") + io.write("Data:\n") + for i,dp in ipairs(data) do + io.write(os.date("%t", start), " (", start, "): ") + start = start + step + for j,v in ipairs(dp) do + io.write(v, " ") + end + io.write("\n") + end =head1 AUTHOR Fidelis Assis Efidelis@pobox.comE + + + -- 2.11.0