INSTALL - kvmtool - Git at Google

  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, RISC-V) 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
 - riscv
 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, ARM/ARM64 and RISC-V 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
 $ make libfdt

 After compiling libfdt, the library can be installed system-wide:

 $ TRIPLET=$($CC -dumpmachine)
 $ SYSROOT=$($CC -print-sysroot)
 $ 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.

 Alternatively, if installing the shared library is not desirable or possible,
 you can instruct kvmtool to use the static library when compiling by using the
 variable LIBFDT_DIR. LIBFDT_DIR should point to the dtc/libfdt directory.
 kvmtool will include the static library LIBFDT_DIR/libfdt.a in the executable,
 removing the need for the shared library to be present on the system.
 LIBFDT_DIR, when set, takes precedence over the system library.
	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, RISC-V) 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
	- riscv
	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, ARM/ARM64 and RISC-V 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
	$ make libfdt

	After compiling libfdt, the library can be installed system-wide:

	$ TRIPLET=$($CC -dumpmachine)
	$ SYSROOT=$($CC -print-sysroot)
	$ 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.

	Alternatively, if installing the shared library is not desirable or possible,
	you can instruct kvmtool to use the static library when compiling by using the
	variable LIBFDT_DIR. LIBFDT_DIR should point to the dtc/libfdt directory.
	kvmtool will include the static library LIBFDT_DIR/libfdt.a in the executable,
	removing the need for the shared library to be present on the system.
	LIBFDT_DIR, when set, takes precedence over the system library.