From 37e632b7b8e1bd8c9893bb8e3c9a8691c78256a4 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Wed, 24 Nov 2010 18:49:37 +0000 Subject: [PATCH] ruby: Translate C examples into Ruby and include documentation. --- .gitignore | 3 ++ Makefile.am | 3 +- configure.ac | 2 +- examples/guestfs-examples.pod | 1 + ocaml/examples/guestfs-ocaml.pod | 1 + python/examples/guestfs-python.pod | 1 + ruby/examples/LICENSE | 2 ++ ruby/examples/Makefile.am | 39 ++++++++++++++++++++++ ruby/examples/create_disk.rb | 64 ++++++++++++++++++++++++++++++++++++ ruby/examples/guestfs-ruby.pod | 67 ++++++++++++++++++++++++++++++++++++++ ruby/examples/inspect_vm.rb | 59 +++++++++++++++++++++++++++++++++ src/guestfs.pod | 4 +-- 12 files changed, 242 insertions(+), 4 deletions(-) create mode 100644 ruby/examples/LICENSE create mode 100644 ruby/examples/Makefile.am create mode 100644 ruby/examples/create_disk.rb create mode 100644 ruby/examples/guestfs-ruby.pod create mode 100644 ruby/examples/inspect_vm.rb diff --git a/.gitignore b/.gitignore index 1f97d7b..3416fbb 100644 --- a/.gitignore +++ b/.gitignore @@ -118,6 +118,7 @@ html/guestfs.3.html html/guestfs-examples.3.html html/guestfs-ocaml.3.html html/guestfs-python.3.html +html/guestfs-ruby.3.html html/guestmount.1.html html/recipes.html html/virt-cat.1.html @@ -279,6 +280,8 @@ regressions/test2.img regressions/test.err regressions/test.out ruby/bindtests.rb +ruby/examples/guestfs-ruby.3 +ruby/examples/stamp-guestfs-ruby.pod ruby/ext/guestfs/extconf.h ruby/ext/guestfs/_guestfs.bundle ruby/ext/guestfs/_guestfs.c diff --git a/Makefile.am b/Makefile.am index 8371984..5b19c30 100644 --- a/Makefile.am +++ b/Makefile.am @@ -49,7 +49,7 @@ if HAVE_PYTHON SUBDIRS += python python/examples endif if HAVE_RUBY -SUBDIRS += ruby +SUBDIRS += ruby ruby/examples endif if HAVE_JAVA SUBDIRS += java @@ -105,6 +105,7 @@ HTMLFILES = \ html/guestfs-examples.3.html \ html/guestfs-ocaml.3.html \ html/guestfs-python.3.html \ + html/guestfs-ruby.3.html \ html/guestfish.1.html \ html/guestmount.1.html \ html/virt-cat.1.html \ diff --git a/configure.ac b/configure.ac index f3235c3..4d5e268 100644 --- a/configure.ac +++ b/configure.ac @@ -854,7 +854,7 @@ AC_CONFIG_FILES([Makefile ocaml/Makefile ocaml/examples/Makefile perl/Makefile python/Makefile python/examples/Makefile - ruby/Makefile ruby/Rakefile + ruby/Makefile ruby/Rakefile ruby/examples/Makefile java/Makefile haskell/Makefile inspector/Makefile diff --git a/examples/guestfs-examples.pod b/examples/guestfs-examples.pod index aa81e8a..787a370 100644 --- a/examples/guestfs-examples.pod +++ b/examples/guestfs-examples.pod @@ -35,6 +35,7 @@ libguestfs, you also need to read L. L, L, L, +L, L, L. diff --git a/ocaml/examples/guestfs-ocaml.pod b/ocaml/examples/guestfs-ocaml.pod index da09135..21c4a70 100644 --- a/ocaml/examples/guestfs-ocaml.pod +++ b/ocaml/examples/guestfs-ocaml.pod @@ -80,6 +80,7 @@ function that you called. L, L, L, +L, L, L. diff --git a/python/examples/guestfs-python.pod b/python/examples/guestfs-python.pod index 49ff787..9cf7809 100644 --- a/python/examples/guestfs-python.pod +++ b/python/examples/guestfs-python.pod @@ -44,6 +44,7 @@ Type: L, L, L, +L, L. =head1 AUTHORS diff --git a/ruby/examples/LICENSE b/ruby/examples/LICENSE new file mode 100644 index 0000000..18de9ee --- /dev/null +++ b/ruby/examples/LICENSE @@ -0,0 +1,2 @@ +All the examples in the 'ruby/examples' subdirectory may be freely +copied, modified and distributed without any restrictions. diff --git a/ruby/examples/Makefile.am b/ruby/examples/Makefile.am new file mode 100644 index 0000000..6e94acf --- /dev/null +++ b/ruby/examples/Makefile.am @@ -0,0 +1,39 @@ +# libguestfs Ruby examples +# Copyright (C) 2010 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., 675 Mass Ave, Cambridge, MA 02139, USA. + +EXTRA_DIST = \ + LICENSE \ + create_disk.rb \ + inspect_vm.rb \ + guestfs-ruby.pod + +CLEANFILES = stamp-guestfs-ruby.pod + +man_MANS = guestfs-ruby.3 +noinst_DATA = $(top_builddir)/html/guestfs-ruby.3.html + +guestfs-ruby.3 $(top_builddir)/html/guestfs-ruby.3.html: stamp-guestfs-ruby.pod + +stamp-guestfs-ruby.pod: guestfs-ruby.pod create_disk.rb inspect_vm.rb + $(top_srcdir)/podwrapper.sh \ + --section 3 \ + --man guestfs-ruby.3 \ + --html $(top_builddir)/html/guestfs-ruby.3.html \ + --verbatim create_disk.rb:@EXAMPLE1@ \ + --verbatim inspect_vm.rb:@EXAMPLE2@ \ + $< + touch $@ diff --git a/ruby/examples/create_disk.rb b/ruby/examples/create_disk.rb new file mode 100644 index 0000000..16871cb --- /dev/null +++ b/ruby/examples/create_disk.rb @@ -0,0 +1,64 @@ +# Example showing how to create a disk image. + +require 'guestfs' + +output = "disk.img" + +g = Guestfs::Guestfs.new() + +# Create a raw-format sparse disk image, 512 MB in size. +File.open(output, "w") { + |f| f.truncate(512 * 1024 * 1024) +} + +# Set the trace flag so that we can see each libguestfs call. +g.set_trace(1) + +# Set the autosync flag so that the disk will be synchronized +# automatically when the libguestfs handle is closed. +g.set_autosync(1) + +# Attach the disk image to libguestfs. +g.add_drive_opts(output, :format => "raw") + +# 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 devices.length != 1 then + raise "error: expected a single device from list-devices" +end + +# Partition the disk as one single MBR partition. +g.part_disk(devices[0], "mbr") + +# Get the list of partitions. We expect a single element, which +# is the partition we have just created. +partitions = g.list_partitions() +if partitions.length != 1 then + raise "error: expected a single partition from list-partitions" +end + +# Create a filesystem on the partition. +g.mkfs("ext4", partitions[0]) + +# Now mount the filesystem so that we can add files. +g.mount_options("", partitions[0], "/") + +# 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 'autosync' was set (above) we can just close the handle +# and the disk contents will be synchronized. You can also do +# this manually by calling g#umount_all and g#sync. +g.close() diff --git a/ruby/examples/guestfs-ruby.pod b/ruby/examples/guestfs-ruby.pod new file mode 100644 index 0000000..d3ce928 --- /dev/null +++ b/ruby/examples/guestfs-ruby.pod @@ -0,0 +1,67 @@ +=encoding utf8 + +=head1 NAME + +guestfs-ruby - How to use libguestfs from Ruby + +=head1 SYNOPSIS + + require 'guestfs' + g = Guestfs::Guestfs.new() + g.add_drive_opts("disk.img", + :readonly => 1, :format => "raw") + g.launch() + +=head1 DESCRIPTION + +This manual page documents how to call libguestfs from the Ruby +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. + +=head2 EXCEPTIONS + +Errors from libguestfs functions are mapped into the C +exception. This has a single parameter which is the error message (a +string). + +=head1 EXAMPLE 1: CREATE A DISK IMAGE + +@EXAMPLE1@ + +=head1 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE + +@EXAMPLE2@ + +=head1 SEE ALSO + +L, +L, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2010 Red Hat Inc. L + +The examples in this manual page may be freely copied, modified and +distributed without any restrictions. + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2 of the License, or (at your option) any later version. + +This library 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 +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA diff --git a/ruby/examples/inspect_vm.rb b/ruby/examples/inspect_vm.rb new file mode 100644 index 0000000..032dec4 --- /dev/null +++ b/ruby/examples/inspect_vm.rb @@ -0,0 +1,59 @@ +# Example showing how to inspect a virtual machine disk. + +require 'guestfs' + +if ARGV.length == 0 + puts "usage: inspect_vm disk.img" + exit 1 +end +disk = ARGV[0] + +g = Guestfs::Guestfs.new() + +# Attach the disk image read-only to libguestfs. +g.add_drive_opts(disk, :readonly => 1) + +# Run the libguestfs back-end. +g.launch() + +# Ask libguestfs to inspect for operating systems. +roots = g.inspect_os() +if roots.length == 0 + puts "inspect_vm: no operating systems found" + exit 1 +end + +for root in roots do + printf("Root device: %s\n", root) + + # Print basic information about the operating system. + printf(" Product name: %s\n", g.inspect_get_product_name(root)) + printf(" Version: %d.%d\n", + g.inspect_get_major_version(root), + g.inspect_get_minor_version(root)) + printf(" Type: %s\n", g.inspect_get_type(root)) + printf(" Distro: %s\n", 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) + mps = mps.sort {|a,b| a[0].length <=> b[0].length} + for mp in mps do + g.mount_ro(mp[1], mp[0]) + end + + # If /etc/issue.net file exists, print up to 3 lines. + filename = "/etc/issue.net" + if g.is_file filename then + printf("--- %s ---\n", filename) + lines = g.head_n(3, filename) + for line in lines do + puts line + end + end + + # Unmount everything. + g.umount_all() +end diff --git a/src/guestfs.pod b/src/guestfs.pod index a8e530f..677d944 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -676,8 +676,7 @@ For documentation see L. =item B -Use the Guestfs module. There is no Ruby-specific documentation, but -you can find examples written in Ruby in the libguestfs source. +For documentation see L. =item B @@ -2085,6 +2084,7 @@ enough. L, L, L, +L, L, L, L, -- 1.8.3.1