Add Lua bindings.

These are relatively complete, although only lightly tested.  Missing:

 - events
 - last_errno
 - user_cancel

lua/Makefile.am

@@ -0,0 +1,79 @@
+# libguestfs Lua bindings
+# Copyright (C) 2012 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+include $(top_srcdir)/subdir-rules.mk
+
+lualibdir = $(libdir)/lua/$(LUA_VERSION)
+
+generator_built = \
+	lua-guestfs.c
+
+EXTRA_DIST = \
+	$(generator_built)
+
+CLEANFILES = *~ guestfs.so
+
+if HAVE_LUA
+
+# Libtool forces us to use 'libluaguestfs.so' instead of the desired
+# name 'guestfs.so'.  However we'll rename it in the install hook.
+# Cannot use 'noinst' here as that prevents the shared library from
+# being built at all.
+lualib_LTLIBRARIES = libluaguestfs.la
+libluaguestfs_la_SOURCES = lua-guestfs.c
+
+libluaguestfs_la_CFLAGS = \
+	$(WARN_CFLAGS) $(WERROR_CFLAGS) \
+	-I$(top_srcdir)/src -I$(top_builddir)/src
+libluaguestfs_la_LIBADD = $(top_builddir)/src/libguestfs.la
+libluaguestfs_la_LDFLAGS = -avoid-version -shared
+
+# Hack so we can run without installing.
+noinst_DATA = guestfs.so
+guestfs.so: libluaguestfs.la
+	ln -sf .libs/libluaguestfs.so $@
+
+# Tests.
+TESTS_ENVIRONMENT = $(top_builddir)/run --test
+TESTS = \
+	tests/010-load.lua \
+	tests/020-create.lua \
+	tests/025-create-flags.lua \
+	tests/030-config.lua \
+	tests/070-optargs.lua
+
+if ENABLE_APPLIANCE
+TESTS += \
+	tests/050-lvcreate.lua \
+	tests/060-readdir.lua
+endif
+
+EXTRA_DIST += \
+	tests/010-load.lua \
+	tests/020-create.lua \
+	tests/025-create-flags.lua \
+	tests/030-config.lua \
+	tests/050-lvcreate.lua \
+	tests/060-readdir.lua \
+	tests/070-optargs.lua
+
+# Custom install rule.
+install-data-hook:
+	mkdir -p $(DESTDIR)$(lualibdir)
+	mv $(DESTDIR)$(lualibdir)/libluaguestfs.so $(DESTDIR)$(lualibdir)/guestfs.so
+
+endif

lua/examples/LICENSE

@@ -0,0 +1,2 @@
+All the examples in the lua/examples/ subdirectory may be freely
+copied without any restrictions.

lua/examples/Makefile.am

@@ -0,0 +1,40 @@
+# libguestfs Lua examples
+# Copyright (C) 2012 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+EXTRA_DIST = \
+	LICENSE \
+	create_disk.lua \
+	inspect_vm.lua \
+	guestfs-lua.pod
+
+CLEANFILES = stamp-guestfs-lua.pod
+
+man_MANS = guestfs-lua.3
+noinst_DATA = $(top_builddir)/html/guestfs-lua.3.html
+
+guestfs-lua.3 $(top_builddir)/html/guestfs-lua.3.html: stamp-guestfs-lua.pod
+
+stamp-guestfs-lua.pod: guestfs-lua.pod create_disk.lua inspect_vm.lua
+	$(PODWRAPPER) \
+	  --section 3 \
+	  --man guestfs-lua.3 \
+	  --html $(top_builddir)/html/guestfs-lua.3.html \
+	  --verbatim $(srcdir)/create_disk.lua:@EXAMPLE1@ \
+	  --verbatim $(srcdir)/inspect_vm.lua:@EXAMPLE2@ \
+	  --license examples \
+	  $<
+	touch $@

lua/examples/create_disk.lua

@@ -0,0 +1,66 @@
+-- Example showing how to create a disk image.
+
+require "guestfs"
+
+output = "disk.img"
+
+g = Guestfs.create ()
+
+-- Create a raw-format sparse disk image, 512 MB in size.
+file = io.open (output, "w")
+file:seek ("set", 512 * 1024 * 1024)
+file:write (' ')
+file:close ()
+
+-- Set the trace flag so that we can see each libguestfs call.
+g:set_trace (true)
+
+-- Attach the disk image to libguestfs.
+g:add_drive (output, { format = "raw", readonly = false })
+
+-- Run the libguestfs back-end.
+g:launch ()
+
+-- Get the list of devices.  Because we only added one drive
+-- above, we expect that this list should contain a single
+-- element.
+devices = g:list_devices ()
+if table.getn (devices) ~= 1 then
+   error "expected a single device from list-devices"
+end
+
+-- Partition the disk as one single MBR partition.
+g:part_disk (devices[1], "mbr")
+
+-- Get the list of partitions.  We expect a single element, which
+-- is the partition we have just created.
+partitions = g:list_partitions ()
+if table.getn (partitions) ~= 1 then
+   error "expected a single partition from list-partitions"
+end
+
+-- Create a filesystem on the partition.
+g:mkfs ("ext4", partitions[1])
+
+-- Now mount the filesystem so that we can add files.
+g:mount (partitions[1], "/")
+
+-- Create some files and directories.
+g:touch ("/empty")
+message = "Hello, world\n"
+g:write ("/hello", message)
+g:mkdir ("/foo")
+
+-- This one uploads the local file /etc/resolv.conf into
+-- the disk image.
+g:upload ("/etc/resolv.conf", "/foo/resolv.conf")
+
+-- Because we wrote to the disk and we want to detect write
+-- errors, call g:shutdown.  You don't need to do this:
+-- g:close will do it implicitly.
+g:shutdown ()
+
+-- Note also that handles are automatically closed if they are
+-- reaped by the garbage collector.  You only need to call close
+-- if you want to close the handle right away.
+g:close ()

lua/examples/guestfs-lua.pod

@@ -0,0 +1,97 @@
+=encoding utf8
+
+=head1 NAME
+
+guestfs-lua - How to use libguestfs from Lua
+
+=head1 SYNOPSIS
+
+ require "guestfs"
+ g = Guestfs.create ()
+ g:add_drive ("test.img", { format = "raw", readonly = "true" })
+ g:launch ()
+ devices = g:list_devices ()
+ g:close ()
+
+=head1 DESCRIPTION
+
+This manual page documents how to call libguestfs from the Lua
+programming language.  This page just documents the differences from
+the C API and gives some examples.  If you are not familiar with using
+libguestfs, you also need to read L<guestfs(3)>.
+
+=head2 OPENING AND CLOSING THE HANDLE
+
+To create a new handle, call:
+
+ g = Guestfs.create ()
+
+You can also use the optional arguments:
+
+ g = Guestfs.create { environment = 0, close_on_exit = 0 }
+
+to set the flags C<GUESTFS_CREATE_NO_ENVIRONMENT>
+and/or C<GUESTFS_CREATE_NO_CLOSE_ON_EXIT>.
+
+The handle will be closed by the garbage collector, but you can
+also close it explicitly by doing:
+
+ g:close ()
+
+=head2 CALLING METHODS
+
+Use the ordinary Lua convention for calling methods on the handle.
+For example:
+
+ g:set_verbose (true)
+
+=head2 FUNCTIONS WITH OPTIONAL ARGUMENTS
+
+For functions that take optional arguments, the first arguments are
+the non-optional ones.  The optional final argument is a table
+supplying the optional arguments.
+
+ g:add_drive ("test.img")
+
+or:
+
+ g:add_drive ("test.img", { format = "raw", readonly = "true" })
+
+=head2 64 BIT VALUES
+
+Currently 64 bit values must be passed as strings, and are returned as
+strings.  This is because 32 bit Lua cannot handle 64 bit integers
+properly.  We hope to come up with a better solution later.
+
+=head2 ERRORS
+
+Errors are converted into exceptions.  Use C<pcall> to catch these.
+
+=head1 EXAMPLE 1: CREATE A DISK IMAGE
+
+@EXAMPLE1@
+
+=head1 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE
+
+@EXAMPLE2@
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<guestfs-examples(3)>,
+L<guestfs-java(3)>,
+L<guestfs-ocaml(3)>,
+L<guestfs-perl(3)>,
+L<guestfs-python(3)>,
+L<guestfs-recipes(1)>,
+L<guestfs-ruby(3)>,
+L<http://www.erlang.org/>.
+L<http://libguestfs.org/>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2012 Red Hat Inc.

lua/examples/inspect_vm.lua

@@ -0,0 +1,62 @@
+-- Example showing how to inspect a virtual machine disk.
+
+require "guestfs"
+
+if table.getn (arg) == 1 then
+   disk = arg[1]
+else
+   error ("usage: inspect_vm disk.img")
+end
+
+g = Guestfs.create ()
+
+-- Attach the disk image read-only to libguestfs.
+g:add_drive (disk, { -- format:"raw"
+                     readonly = true })
+
+-- Run the libguestfs back-end.
+g:launch ()
+
+-- Ask libguestfs to inspect for operating systems.
+roots = g:inspect_os ()
+if table.getn (roots) == 0 then
+   error ("inspect_vm: no operating systems found")
+end
+
+for _, root in ipairs (roots) do
+   print ("Root device: ", root)
+
+   -- Print basic information about the operating system.
+   print ("  Product name: ", g:inspect_get_product_name (root))
+   print ("  Version:      ",
+          g:inspect_get_major_version (root),
+          g:inspect_get_minor_version (root))
+   print ("  Type:         ", g:inspect_get_type (root))
+   print ("  Distro:       ", g:inspect_get_distro (root))
+
+   -- Mount up the disks, like guestfish -i.
+   --
+   -- Sort keys by length, shortest first, so that we end up
+   -- mounting the filesystems in the correct order.
+   mps = g:inspect_get_mountpoints (root)
+   table.sort (mps,
+               function (a, b)
+                  return string.len (a) < string.len (b)
+               end)
+   for mp,dev in pairs (mps) do
+      pcall (function () g:mount_ro (dev, mp) end)
+   end
+
+   -- If /etc/issue.net file exists, print up to 3 lines.
+   filename = "/etc/issue.net"
+   if g:is_file (filename) then
+      print ("--- ", filename, " ---")
+      lines = g:head_n (3, filename)
+      for _, line in ipairs (lines) do
+         print (line)
+      end
+   end
+
+   -- Unmount everything.
+   g:umount_all ()
+end

lua/tests/010-load.lua

@@ -0,0 +1,19 @@
+#!/usr/bin/lua
+-- libguestfs Lua bindings -*- lua -*-
+-- Copyright (C) 2012 Red Hat Inc.
+--
+-- This program is free software; you can redistribute it and/or modify
+-- it under the terms of the GNU General Public License as published by
+-- the Free Software Foundation; either version 2 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU General Public License for more details.
+--
+-- You should have received a copy of the GNU General Public License
+-- along with this program; if not, write to the Free Software
+-- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require "guestfs"

lua/tests/020-create.lua

@@ -0,0 +1,21 @@
+#!/usr/bin/lua
+-- libguestfs Lua bindings -*- lua -*-
+-- Copyright (C) 2012 Red Hat Inc.
+--
+-- This program is free software; you can redistribute it and/or modify
+-- it under the terms of the GNU General Public License as published by
+-- the Free Software Foundation; either version 2 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU General Public License for more details.
+--
+-- You should have received a copy of the GNU General Public License
+-- along with this program; if not, write to the Free Software
+-- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require "guestfs"
+
+local g = Guestfs.create ()

lua/tests/025-create-flags.lua

@@ -0,0 +1,21 @@
+#!/usr/bin/lua
+-- libguestfs Lua bindings -*- lua -*-
+-- Copyright (C) 2012 Red Hat Inc.
+--
+-- This program is free software; you can redistribute it and/or modify
+-- it under the terms of the GNU General Public License as published by
+-- the Free Software Foundation; either version 2 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU General Public License for more details.
+--
+-- You should have received a copy of the GNU General Public License
+-- along with this program; if not, write to the Free Software
+-- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require "guestfs"
+
+local g = Guestfs.create { environment = 0 }

lua/tests/030-config.lua

@@ -0,0 +1,42 @@
+#!/usr/bin/lua
+-- libguestfs Lua bindings -*- lua -*-
+-- Copyright (C) 2012 Red Hat Inc.
+--
+-- This program is free software; you can redistribute it and/or modify
+-- it under the terms of the GNU General Public License as published by
+-- the Free Software Foundation; either version 2 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU General Public License for more details.
+--
+-- You should have received a copy of the GNU General Public License
+-- along with this program; if not, write to the Free Software
+-- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require "guestfs"
+
+local g = Guestfs.create ()
+
+local verbose = g:get_verbose ()
+g:set_verbose (true)
+g:set_verbose (verbose)
+
+g:set_autosync (false)
+g:set_autosync (true)
+
+g:set_path (".")
+if g:get_path () ~= "." then
+   error ()
+end
+
+g:add_drive ("/dev/null")
+
+local version = g:version ()
+for k,v in pairs (version) do
+   print(k,v)
+end
+
+g:close ()

lua/tests/050-lvcreate.lua

@@ -0,0 +1,47 @@
+#!/usr/bin/lua
+-- libguestfs Lua bindings -*- lua -*-
+-- Copyright (C) 2012 Red Hat Inc.
+--
+-- This program is free software; you can redistribute it and/or modify
+-- it under the terms of the GNU General Public License as published by
+-- the Free Software Foundation; either version 2 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU General Public License for more details.
+--
+-- You should have received a copy of the GNU General Public License
+-- along with this program; if not, write to the Free Software
+-- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require "guestfs"
+
+local g = Guestfs.create ()
+
+file = io.open ("test.img", "w")
+file:seek ("set", 500 * 1024 * 1024)
+file:write (' ')
+file:close ()
+
+g:add_drive ("test.img")
+
+g:launch ()
+
+g:pvcreate ("/dev/sda")
+g:vgcreate ("VG", {"/dev/sda"})
+g:lvcreate ("LV1", "VG", 200)
+g:lvcreate ("LV2", "VG", 200)
+
+local lvs = g:lvs ()
+if table.getn (lvs) ~= 2 or lvs[1] ~= "/dev/VG/LV1" or lvs[2] ~= "/dev/VG/LV2"
+then
+   error ("g:lvs returned incorrect result")
+end
+
+g:shutdown ()
+
+g:close ()
+
+os.remove ("test.img")

lua/tests/060-readdir.lua

@@ -0,0 +1,65 @@
+#!/usr/bin/lua
+-- libguestfs Lua bindings -*- lua -*-
+-- Copyright (C) 2012 Red Hat Inc.
+--
+-- This program is free software; you can redistribute it and/or modify
+-- it under the terms of the GNU General Public License as published by
+-- the Free Software Foundation; either version 2 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU General Public License for more details.
+--
+-- You should have received a copy of the GNU General Public License
+-- along with this program; if not, write to the Free Software
+-- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require "guestfs"
+
+local g = Guestfs.create ()
+
+file = io.open ("test.img", "w")
+file:seek ("set", 10 * 1024 * 1024)
+file:write (' ')
+file:close ()
+
+g:add_drive ("test.img")
+
+g:launch ()
+
+g:part_disk ("/dev/sda", "mbr")
+g:mkfs ("ext2", "/dev/sda1")
+g:mount ("/dev/sda1", "/")
+g:mkdir ("/p")
+g:touch ("/q")
+
+local dirs = g:readdir ("/")
+
+function print_dirs(dirs)
+   for i,dentry in ipairs (dirs) do
+      for k,v in pairs (dentry) do
+         print(i, k, v)
+      end
+   end
+end
+
+print_dirs (dirs)
+table.sort (dirs, function (a,b) return a["name"] < b["name"] end)
+print_dirs (dirs)
+
+-- Slots 1, 2, 3 contain "." and ".." and "lost+found" respectively.
+
+if (dirs[4]["name"] ~= "p") then
+   error "incorrect name in slot 4"
+end
+if (dirs[5]["name"] ~= "q") then
+   error "incorrect name in slot 5"
+end
+
+g:shutdown ()
+
+g:close ()
+
+os.remove ("test.img")

lua/tests/070-optargs.lua

@@ -0,0 +1,25 @@
+#!/usr/bin/lua
+-- libguestfs Lua bindings -*- lua -*-
+-- Copyright (C) 2012 Red Hat Inc.
+--
+-- This program is free software; you can redistribute it and/or modify
+-- it under the terms of the GNU General Public License as published by
+-- the Free Software Foundation; either version 2 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU General Public License for more details.
+--
+-- You should have received a copy of the GNU General Public License
+-- along with this program; if not, write to the Free Software
+-- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require "guestfs"
+
+local g = Guestfs.create ()
+
+g:add_drive ("/dev/null")
+g:add_drive ("/dev/null", { readonly = true })
+g:add_drive ("/dev/null", { format = "raw", readonly = false })