diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000..ca8e022 --- /dev/null +++ b/INSTALL @@ -0,0 +1,99 @@ + Installation instructions for kvmtool +--------------------------------------- + +========================================================================== +For the impatient: +Just typing "make" should do the trick most of the times. +You will get a binary called "lkvm" which is self-contained. +No extra libraries or files need to be installed. +========================================================================== + +"make install" will copy the compiled file into $HOME/bin, this can be +changed by providing "prefix=" on the make command-line. DESTDIR will be +honoured. + +Prerequisites +-------------- +For compilation you will need a recent GNU tool chain (binutils, gcc, make), +also the standard C library. + +For deb based systems: + $ sudo apt-get install build-essential + On x86-64 systems you have to add the 32-bit compat headers: + $ sudo apt-get install libc6-dev-i386 +For Fedora based systems: + # yum install glibc-static +For OpenSUSE based systems: + # zypper install glibc-devel-static + +Architectures which require device tree (PowerPC, ARM, ARM64) also require +libfdt. + deb: $ sudo apt-get install libfdt-dev + Fedora: # yum install libfdt-devel + OpenSUSE: # zypper install libfdt1-devel +Also see "Cross compiling" below. + +Optional libraries +------------------- +By running "make" some checks are invoked that determine the availability +of certain optional libraries. Those are: +- libbfd: enable symbol look-up support in debug mode +- gtk3: enable support for displaying the guest framebuffer in a GTK+-3 window +- vncserver: enable support for exporting the guest framebuffer in a VNC session +- SDL: enable support for displaying the guest framebuffer in a SDL window +- zlib: enable support for compressed QCOW images +- aio: enable support for asynchronous I/O +(Note that a guest framebuffer is currently only supported on x86.) +So for the full glory you would need: +(on a .deb based system): +$ sudo apt-get install binutils-dev libgtk-3-dev libvncserver-dev libsdl2-dev \ + zlib1g-dev libaio-dev +(on RPM based systems): +# $TOOL install binutils-devel gtk3-devel libvncserver-devel SDL-devel \ + zlib-devel libaio-devel +$TOOL is "yum" for Fedora and "zypper" for OpenSUSE. + +Cross compiling +---------------- +The Makefile will honour the CROSS_COMPILE environment variable when calling +the compiler and the linker binary. To trigger cross compilation, also set ARCH +to the Linux name of the architecture. Architectures supported: +- i386 +- x86_64 +- powerpc +- arm +- arm64 +- mips +If ARCH is not provided, the target architecture will be automatically +determined by running "uname -m" on your host, resulting in a native build. + +To cross-compile to ARM for instance, install a cross-compiler, put the +required libraries in the cross-compiler's SYSROOT and type: +$ make CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm + +Missing libraries when cross-compiling +--------------------------------------- +The cross-compiler will look for target libraries in its SYSROOT directory, +so you need to put the header and library files (.so) there. +While most cross compiler packages come with the target's glibc already +installed, optional libraries (or libfdt) maybe not. +On multiarch system you should be able to install those be appending +the architecture name after the package (example for ARM64): +$ sudo apt-get install libfdt-dev:arm64 + +PowerPC and ARM/ARM64 require libfdt to be installed. If you cannot use +precompiled mulitarch packages, you could either copy the required header and +library files from an installed target system into the SYSROOT (you will need +/usr/include/*fdt*.h and /usr/lib64/libfdt-v.v.v.so and its symlinks), or you +can cross-compile the libfdt library yourself: + +$ git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git +$ cd dtc +$ export CC=${CROSS_COMPILE}gcc +$ TRIPLET=$($CC -dumpmachine) +$ SYSROOT=$($CC -print-sysroot) +$ make libfdt +$ sudo make DESTDIR=$SYSROOT PREFIX=/usr LIBDIR=/usr/lib/$TRIPLET install-lib install-includes + +This assumes a multiarch-enabled system, if there is no per-arch directory for +libraries, replace the LIBDIR paths above with LIBDIR=/usr/lib or /usr/lib64. diff --git a/README b/README index 97747d6..06e72c9 100644 --- a/README +++ b/README @@ -1,5 +1,12 @@ Native Linux KVM tool ===================== + +kvmtool is a lightweight tool for hosting KVM guests. As a pure virtualization +tool it only supports guests using the same architecture, though it supports +running 32-bit guests on those 64-bit architectures that allow this. + +From the original announcement email: +------------------------------------------------------- The goal of this tool is to provide a clean, from-scratch, lightweight KVM host tool implementation that can boot Linux guest images (just a hobby, won't be big and professional like QEMU) with no BIOS @@ -14,20 +21,17 @@ Right now it can boot a Linux image and provide you output via a serial console, over the host terminal, i.e. you can use it to boot a guest Linux image in a terminal or over ssh and log into the guest without much guest or host side setup work needed. +-------------------------- -1. To try out the tool, clone the git repository: +This is the stand-alone version which does not live inside a Linux +kernel tree. +1. To check it out, clone the main git repository: - git clone git://github.com/penberg/linux-kvm.git + git clone git://git.kernel.org/pub/scm/linux/kernel/git/will/kvmtool.git -or alternatively, if you already have a kernel source tree: +2. Compile the tool (for more elaborate instructions see INSTALL): - git remote add kvm-tool git://github.com/penberg/linux-kvm.git - git remote update - git checkout kvm-tool/master -b kvm-tool - -2. Compile the tool: - - cd tools/kvm && make + cd kvmtool && make 3. Download a raw userspace image: @@ -92,21 +96,3 @@ See the following thread for original discussion for motivation of this project: http://thread.gmane.org/gmane.linux.kernel/962051/focus=962620 - -Build dependencies -===================== -For deb based systems: -32-bit: -sudo apt-get install build-essential -64-bit: -sudo apt-get install build-essential libc6-dev-i386 - -For rpm based systems: -32-bit: -yum install glibc-devel -64-bit: -yum install glibc-devel glibc-static - -On 64-bit Arch Linux make sure the multilib repository is enabled in your -/etc/pacman.conf and run -pacman -Sy lib32-glibc