Commit 8a702ca4 authored by Daniel P. Berrange's avatar Daniel P. Berrange

Added POD docs & RPM build

parent 0538ddfb
^blib/
^pm_to_blib$
^Makefile$
^Makefile\.old$
.*~$
^Virt\.bs$
^Virt\.c$
^Virt\.o$
^perl-Sys-Virt\.spec$
^Sys-Virt-.*\.tar\.gz$
^MANIFEST$
Sys::Virt Authors
=================
Sys::Virt is written and maintained by
Daniel P. Berrange <berrange@redhat.com>
-- End
Sys::Virt Installation
======================
Sys::Virt requires that libvirt already be installed on the
system. The libvirt libraries and header files are located using
the pkg-config database. If libvirt is installed to a prefix
other than /usr, then be sure to set the PKG_CONFIG_PATH environment
variable before building this module.
Regular installation:
$ perl Makefile.PL
$ make
$ sudo make install
Install from non-standard location
$ export PKG_CONFIG_PATH=/some/prefix/lib/pkgconfig
$ perl Makefile.PL
$ make
$ sudo make install
-- End
This diff is collapsed.
......@@ -2,6 +2,7 @@ pm_to_blib
Virt\.o
Virt\.c
Virt\.bs
Virt\.xsc
.*.old
Sys-Virt-
blib
......@@ -13,3 +14,4 @@ CVS
#.*
^Makefile$
^cover_db/
.hg
Sys::Virt Readme
================
This module provides a Perl XS binding for the libvirt APIs. For
further details on libvirt consult its website http://libvirt.org/
The only pre-requisite for this module is libvirt itself. For
installation instructions, consult the INSTALL file.
-- End
......@@ -91,7 +91,7 @@ _open(name, readonly)
RETVAL
void
restore(con, from)
restore_domain(con, from)
virConnectPtr con;
const char *from;
PPCODE:
......@@ -121,7 +121,7 @@ get_type(con)
RETVAL
AV *
list_domain_ids(con)
_list_domain_ids(con)
virConnectPtr con;
PREINIT:
int *ids;
......
#!/bin/sh
#
# This script is used to Test::AutoBuild (http://www.autobuild.org)
# to perform automated builds of the DBus module
# to perform automated builds of the Sys-Virt module
NAME=Net-DBus
NAME=Sys-Virt
set -e
......@@ -40,7 +40,7 @@ make install
rm -f $NAME-*.tar.gz
make dist
exit 0
if [ -f /usr/bin/rpmbuild ]; then
if [ -n "$AUTOBUILD_COUNTER" ]; then
EXTRA_RELEASE=".auto$AUTOBUILD_COUNTER"
......
# -*- perl -*-
use Sys::Virt;
my $con = Sys::Virt->new(address => "", readonly => 1);
print "VMM yype: ", $con->get_type(), "\n";
print "libvirt Version: ", $con->get_major_version(), ".", $con->get_minor_version(), ".", $con->get_micro_version(), "\n";
foreach my $dom (sort { $a->get_id <=> $b->get_id } $con->list_domains) {
print "Domain: '", $dom->get_id(), " " , $dom->get_name(), "\n";
my $info = $dom->get_info;
foreach (sort { $a cmp $b } keys %{$info}) {
print " ", $_, ": ", $info->{$_}, "\n";
}
}
# -*- perl -*-
use Sys::Virt;
if (@ARGV != 1) {
print STDERR "syntax: $0 DOMAIN-NAME\n";
exit 1;
}
my $con = Sys::Virt->new(address => "", readonly => 1);
my $name = shift @ARGV;
my $dom = $con->get_domain_by_name($name);
print $dom->get_xml_description(), "\n";
......@@ -4,6 +4,35 @@
Sys::Virt - interface to libvirt virtual machine management API
=head1 SYNOPSIS
my $vmm = Sys::Virt->new(address => $addr);
my @domains = $vmm->list_domains();
foreach my $dom (@domains) {
print "Domain ", $dom->get_id, " ", $dom->get_name, "\n";
}
=head1 DESCRIPTION
The Sys::Virt module provides a Perl XS binding to the libvirt
virtual machine management APIs. This allows machines running
within arbitrary virtualization containers to be managed with
a consistent API.
=head1 ERROR HANDLING
Any operations in the Sys::Virt API which have failure scenarios
will result in an instance of the L<Sys::Virt::Error> module being
thrown. To catch these errors, simply wrap the method in an eval
block. For details of the information contained in the error objects,
consult the L<Sys::Virt::Error> manual page.
=head1 METHODS
=over 4
=cut
package Sys::Virt;
......@@ -18,6 +47,17 @@ our $VERSION = '0.0.1';
require XSLoader;
XSLoader::load('Sys::Virt', $VERSION);
=item my $vmm = Sys::Virt->new(address => $address, readonly => $ro);
Attach to the virtual machine monitor with the address of C<address>. This
parameter is currently unused, so it is recommended to pass an empty string.
If the optional C<readonly> parameter is supplied, then an unprivileged
connection to the VMM will be attempted. If it is not supplied, then it
defaults to making a fully privileged connection to the VMM. THis in turn
requires that the calling application be running as root.
=cut
sub new {
my $proto = shift;
my $class = ref($proto) || $proto;
......@@ -33,6 +73,15 @@ sub new {
}
=item my $dom = $vmm->create_domain($xml);
Create a new domain based on the XML description passed into the C<$xml>
parameter. The returned object is an instance of the L<Sys::Virt::Domain>
class. This method is not available with unprivilegd connections to
the VMM.
=cut
sub create_domain {
my $self = shift;
my $xml = shift;
......@@ -40,11 +89,17 @@ sub create_domain {
return Sys::Virt::Domain->_new(connection => $self, xml => $xml);
}
=item my @doms = $vmm->list_domains()
Return a list of all domains currently known to the VMM. The elements
in the returned list are instances of the L<Sys::Virt::Domain> class.
=cut
sub list_domains {
my $self = shift;
my $ids = $self->list_domain_ids();
my $ids = $self->_list_domain_ids();
my @domains;
foreach my $id (@{$ids}) {
......@@ -53,6 +108,79 @@ sub list_domains {
return @domains;
}
=item my $dom = $vmm->get_domain_by_name($name)
Return the domain with a name of C<$name>. The returned object is
an instance of the L<Sys::Virt::Domain> class.
=cut
sub get_domain_by_name {
my $self = shift;
my $name = shift;
return Sys::Virt::Domain->_new(connection => $self, name => $name);
}
=item my $dom = $vmm->get_domain_by_id($id)
Return the domain with a local id of C<$id>. The returned object is
an instance of the L<Sys::Virt::Domain> class.
=cut
sub get_domain_by_id {
my $self = shift;
my $id = shift;
return Sys::Virt::Domain->_new(connection => $self, id => $id);
}
=item my $dom = $vmm->get_domain_by_uuid($uuid)
Return the domain with a globally unique id of C<$uuid>. The returned object is
an instance of the L<Sys::Virt::Domain> class.
=cut
sub get_domain_by_uuid {
my $self = shift;
my $uuid = shift;
return Sys::Virt::Domain->_new(connection => $self, uuid => $uuid);
}
=item $vmm->restore_domain($savefile)
Recreate a domain from the saved state file given in the C<$savefile> parameter.
=cut
=item my $type = $vmm->get_type()
Return the type of virtualization backend accessed by this VMM object. Curently
the only supported type is C<Xen>.
=cut
=item my $ver = $vmm->get_version()
Return the complete version number as a string encoded in the
formula C<(major * 1000000) + (minor * 1000) + micro>.
=cut
=item my $ver = $vmm->get_major_version
Return the major version number of the libvirt library
=cut
sub get_major_version {
my $self = shift;
my $ver = $self->get_version;
......@@ -60,6 +188,12 @@ sub get_major_version {
}
=item my $ver = $vmm->get_minor_version
Return the minor version number of the libvirt library
=cut
sub get_minor_version {
my $self = shift;
my $ver = $self->get_version;
......@@ -67,9 +201,40 @@ sub get_minor_version {
return ($mver - ($mver % 1000)) / 1000;
}
=item my $ver = $vmm->get_micro_version
Return the micro version number of the libvirt library
=cut
sub get_micro_version {
my $self = shift;
return $self->get_version % 1000;
}
1;
=pod
=back
=head1 BUGS
Hopefully none, but the XS code needs to be audited to ensure it
is not leaking memory
=head1 AUTHORS
Daniel P. Berrange <berrange@redhat.com>
=head1 COPYRIGHT / LICENSE
Copyright (C) 2006 Red Hat
Sys::Virt is distributed under the terms of the GPLv2 or later
=head1 SEE ALSO
L<Sys::Virt::Domain>, L<Sys::Virt::Error>, C<http://libvirt.org>
=cut
......@@ -4,6 +4,15 @@
Sys::Virt - interface to libvirt virtual machine management API
=head1 DESCRIPTION
The C<Sys::Virt::Domain> module represents a guest domain managed
by the virtual machine monitor.
=head1 METHODS
=over 4
=cut
package Sys::Virt::Domain;
......@@ -37,5 +46,113 @@ sub _new {
}
=item my $id = $dom->get_id()
Returns an integer with a locally unique identifier for the
domain.
=item my $uuid = $dom->get_uuid()
Returns a string containing a globally unique identifier for
the domain.
=item my $name = $dom->get_name()
Returns a string with a locally unique name of the domain
=item my $xml = $dom->get_xml_description()
Returns an XML document containing a complete description of
the domain's configuration
=item my $type = $dom->get_os_type()
Returns a string containing the name of the OS type running
within the domain.
=item $dom->suspend
Temporarily stop execution of the domain, allowing later continuation
by calling the C<resume> method.
=item $dom->resume
Resume execution of a domain previously halted with the C<suspend>
method.
=item $dom->save($filename)
Take a snapshot of the domain's state and save the information to
the file named in the C<$filename> parameter. The domain can later
be restored from this file with the C<restore_domain> method on
the L<Sys::Virt> object.
=item $dom->destroy()
Immediately terminate the machine, and remove it from the virtual
machine monitor. The C<$dom> handle is invalid after this call
completes and should not be used again.
=item my $info = $dom->get_info()
Returns a hash reference summarising the execution state of the
domain. The elements of the hash ar
=over 4
=item maxMem
The maximum memory allowed for this domain, in kilobytes
=item memory
The current memory allocated to the domain in kilobytes
=item nrVirtCpus
The current number of virtual CPUs enabled in the domain
=item state
The execution state of the machine, one of the strings
C<running>, C<blocked>, C<paused>, C<shutdown>, C<shutoff>,
C<crashed> or C<unknown>.
=back
=item $dom->set_max_memory($mem)
Set the maximum memory for the domain to the value C<$mem>. The
value of the C<$mem> parameter is specified in kilobytes
=item $mem = $dom->get_max_memory()
Returns the current maximum memory allowed for this domain in
kilobytes.
=item $dom->shutdown()
Request that the guest OS perform a gracefull shutdown and
poweroff.
=cut
1;
=back
=head1 AUTHORS
Daniel P. Berrange <berrange@redhat.com>
=head1 COPYRIGHT / LICENSE
Copyright (C) 2006 Red Hat
Sys::Virt is distributed under the terms of the GPLv2 or later
=head1 SEE ALSO
L<Sys::Virt>, L<Sys::Virt::Error>, C<http://libvirt.org>
=cut
......@@ -2,7 +2,17 @@
=head1 NAME
Sys::Virt::Error - error handling for libvirt APIs
Sys::Virt::Error - error object for libvirt APIs
=head1 DESCRIPTION
The C<Sys::Virt::Error> class provides an encoding of the
libvirt errors. Instances of this object can be thrown by
pretty much any of the Sys::Virt APIs.
=head1 METHODS
=over 4
=cut
......@@ -10,11 +20,58 @@ package Sys::Virt::Error;
use overload ('""' => 'stringify');
=item $err->stringify
Convert the object into string format suitable for printing on a
console to inform a user of the error.
=cut
sub stringify {
my $self = shift;
return "libvirt error code: " . $self->{code} . ", message: " . $self->{message} . ($self->{message} =~ /\n$/ ? "" : "\n");
}
=item my $code = $err->code
Return the raw error code represented by this error
=cut
sub code {
my $self = shift;
return $self->{code}
}
=item my $msg = $err->message
Return an informative message describing the error condition.
=cut
sub message {
my $self = shift;
return $self->{code}
}
1;
=back
=head1 AUTHORS
Daniel P. Berrange <berrange@redhat.com>
=head1 COPYRIGHT / LICENSE
Copyright (C) 2006 Red Hat
Sys::Virt is distributed under the terms of the GPLv2 or later
=head1 SEE ALSO
L<Sys::Virt::Domain>, L<Sys::Virt>, C<http://libvirt.org>
=cut
# -*- rpm-spec -*-
# Copyright (C) 2006 Daniel Berrange <dan@berrange.com>
#
use strict;
die unless (scalar @ARGV == 1);
unless (do 'lib/Sys/Virt.pm')
{
if ($@) { die $@ };
die "lib/Sys/Virt.pm: $!";
}
local $/ = undef;
$_ = <DATA>;
s/\@VERSION\@/$Sys::Virt::VERSION/g;
open SPEC, ">$ARGV[0]" or die "$!";
print SPEC $_;
close SPEC;
__DATA__
# Automatically generated by perl-Sys-Virt.spec.PL
%define perlvendorarch %(perl -e 'use Config; print $Config{installvendorarch}')
%define perlvendorlib %(perl -e 'use Config; print $Config{installvendorlib}')
%define perlvendorprefix %(perl -e 'use Config; print $Config{vendorprefix}')
%define perlvendorman1 %{perlvendorprefix}/share/man/man1
%define perlvendorman3 %{perlvendorprefix}/share/man/man3
%define perlversion %(perl -e 'use Config; print $Config{version}')
%define appname Sys-Virt
%define _extra_release %{?extra_release:%{extra_release}}
Summary: Sys::Virt - Perl API to libvirt library
Name: perl-%{appname}
Version: @VERSION@
Release: 1%{_extra_release}
License: GPL
Group: Development/Tools
Source: %{appname}-%{version}.tar.gz
BuildRoot: /var/tmp/%{appname}-%{version}-root
Requires: perl >= %{perlversion}
%description
Sys::Virt provides an API for using the libvirt library from Perl
%prep
%setup -q -n %{appname}-%{version}
%build
perl Makefile.PL INSTALLDIRS=vendor PREFIX=$RPM_BUILD_ROOT/usr
make
%install
rm -rf $RPM_BUILD_ROOT
make install INSTALLVENDORMAN3DIR=$RPM_BUILD_ROOT%{perlvendorman3} INSTALLVENDORMAN1DIR=$RPM_BUILD_ROOT%{perlvendorman1}
find $RPM_BUILD_ROOT -name perllocal.pod -exec rm -f {} \;
find $RPM_BUILD_ROOT -name .packlist -exec rm -f {} \;
%clean
rm -rf $RPM_BUILD_ROOT
%files
%defattr(-,root,root)
%doc AUTHORS
%doc LICENSE
%doc README
%doc INSTALL
%doc examples/*.pl
%{perlvendorman3}/*
%{perlvendorarch}/Sys/Virt.pm
%{perlvendorarch}/Sys/Virt/
%{perlvendorarch}/auto/Sys/Virt/
%changelog
* Fri Mar 24 2006 <berrange@redhat.com> - 0.0.1-1
- Initial build
use Test::More;
eval "use Test::Pod 1.00";
plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
all_pod_files_ok();
# -*- perl -*-
use Test::More;
eval "use Test::Pod::Coverage 1.00";
plan skip_all => "Test::Pod::Coverage 1.00 required for testing POD coverage" if $@;
all_pod_coverage_ok()
# -*- perl -*-
use Test::More tests => 3;
BEGIN {
use_ok("Sys::Virt") or die;
}
my $con = Sys::Virt->new(address => "");
print "Type: ", $con->get_type(), "\n";
print "Version: ", $con->get_major_version(), " ", $con->get_minor_version(), " ", $con->get_micro_version(), " ", "\n";
foreach my $dom ($con->list_domains) {
print "Dom: '", $dom->get_id(), " " , $dom->get_name(), "\n";
my $info = $dom->get_info;
foreach (sort { $a cmp $b } keys %{$info}) {
print " ", $_, ": ", $info->{$_}, "\n";
}
print "Max ", $dom->get_max_memory, "\n";
print "XML ", $dom->get_xml_description(), "\n";
}
# -*- perl -*-
use Test::More tests => 1;
BEGIN {
use_ok("Sys::Virt") or die;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment