tests: Fix read_file test.

[libguestfs.git] / README

diff --git a/README b/README
index 88fca7d..d56d21e 100644 (file)
--- a/README
+++ b/README
@@ -19,10 +19,17 @@ Libguestfs is a library that can be linked with C and C++ management
 programs (or management programs written in OCaml, Perl, Python, Ruby, Java
 or Haskell).  You can also use it from shell scripts or the command line.
 
 programs (or management programs written in OCaml, Perl, Python, Ruby, Java
 or Haskell).  You can also use it from shell scripts or the command line.
 

-Libguestfs was written by Richard W.M. Jones (rjones@redhat.com).
-For discussion please use the fedora-virt mailing list:
+Libguestfs was written by Richard W.M. Jones (rjones@redhat.com) and
+hacked on by lots of other people.  For discussion, development,
+patches, etc. please use the mailing list:

 
 

-  https://www.redhat.com/mailman/listinfo/fedora-virt
+  http://www.redhat.com/mailman/listinfo/libguestfs
+
+
+Home page
+----------------------------------------------------------------------
+
+  http://libguestfs.org/

 
 
 Requirements
 
 
 Requirements


@@ -31,7 +38,7 @@ Requirements
 - recent QEMU >= 0.10 with vmchannel support
   http://lists.gnu.org/archive/html/qemu-devel/2009-02/msg01042.html
 
 - recent QEMU >= 0.10 with vmchannel support
   http://lists.gnu.org/archive/html/qemu-devel/2009-02/msg01042.html
 

-- febootstrap >= 2.0
+- febootstrap >= 2.3

 
 - fakeroot
 
 
 - fakeroot
 


@@ -67,6 +74,11 @@ bindings
 
 - (Optional) GHC if you want to build the Haskell bindings
 
 
 - (Optional) GHC if you want to build the Haskell bindings
 

+- (Optional) Perl XML::XPath, Sys::Virt modules (for libvirt support
+in virt-inspector).
+
+- (Optional, but highly recommended) perl-libintl for translating perl code.
+

 Running ./configure will check you have all the requirements installed
 on your machine.
 
 Running ./configure will check you have all the requirements installed
 on your machine.
 


@@ -114,10 +126,17 @@ or build from our source RPMs.
 Debian
 ----------------------------------------------------------------------
 
 Debian
 ----------------------------------------------------------------------
 

-libguestfs should build and run on Debian.  At the moment we don't
-provide Debian packages, and because of the appliance it's rather
-complicated to provide a package which could be accepted into the
-Debian repositories.  Want to help?  Please contact us.
+libguestfs is now built as a package in Debian by Guido Gunther and
+the other Debian libvirt maintainers.  See:
+
+http://wiki.debian.org/Teams/DebianLibvirtTeam#Packages
+
+You can build for Debian in two different ways, either building a
+Fedora-based appliance using febootstrap, yum, rpm, fakeroot,
+fakechroot (all packaged in Debian).  However the recommended way is
+to build a Debian-based appliance using debootstrap and debirf.
+
+Both ways are supported by the configure script.

 
 
 qemu
 
 
 qemu


@@ -162,6 +181,62 @@ On some systems, the chmod will not survive a reboot, and you will
 need to make edits to the udev configuration.
 
 
 need to make edits to the udev configuration.
 
 

+Supermin appliance
+----------------------------------------------------------------------
+
+If you configure with --enable-supermin then we will build a supermin
+appliance (supermin = super-minimized).  This is a very specialized
+appliance which is built on-the-fly at runtime (specifically, when you
+call guestfs_launch).
+
+The normal appliance is a self-contained Linux operating system, based
+on the Fedora/RHEL/CentOS Linux distro.  So it contains a complete
+copy of all the libraries and programs needed, like kernel, libc,
+bash, coreutils etc etc.
+
+The supermin appliance removes the kernel and all the executable
+libraries and programs from the appliance.  That just leaves a
+skeleton of config files and some data files, which is obviously
+massively smaller than the normal appliance.  At runtime we rebuild
+the appliance on-the-fly from the libraries and programs on the host
+(eg. pulling in the real /lib/libc.so, the real /bin/bash etc.)
+
+Although this process of rebuilding the appliance each time sounds
+slow, it turns out to be faster than using the prebuilt appliance.
+(Most of the saving comes from not compressing the appliance - it
+transpires that decompressing the appliance is the slowest part of the
+whole boot sequence).  On my machine, a new appliance can be built in
+under a fifth of a second, and the boot time is several seconds
+shorter.
+
+The big advantage of the supermin appliance for distributions like
+Fedora is that it gets security fixes automatically from the host, so
+there is no need to rebuild the whole of libguestfs for a security
+update in some underlying library.
+
+There are several DISADVANTAGES:
+
+It won't work at all except in very narrow, controlled cases like the
+Fedora packaging case.  We control the dependencies of the libguestfs
+RPM tightly to ensure that the required binaries are actually present
+on the host.
+
+Furthermore there are certain unlikely changes in the packages on the
+host which could break a supermin appliance, eg. an updated library
+which depends on an additional data file.
+
+Also supermin appliances are subjected to changes in the host kernel
+which might break compatibility with qemu -- these are, of course,
+real bugs in any case.
+
+Lastly, supermin appliances really can't be moved between branches of
+distributions (eg. built on Fedora 12 and moved to Fedora 10) because
+they are not self-contained and they rely on certain libraries being
+around.  You shouldn't do this anyway.
+
+Use supermin appliances with caution.
+
+

 Notes on cross-architecture support
 ----------------------------------------------------------------------
 
 Notes on cross-architecture support
 ----------------------------------------------------------------------