From 9310fabd26da1d00ddb2a3c0707b780614307a7d Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Wed, 20 Jan 2016 12:17:12 +0000 Subject: [PATCH] docs: Add guestfs-building(1) man page. This contains instructions for building libguestfs from source. --- .gitignore | 2 + README | 407 +-------------------------- docs/Makefile.am | 16 ++ docs/guestfs-building.pod | 578 ++++++++++++++++++++++++++++++++++++++ po-docs/language.mk | 1 + po-docs/podfiles | 1 + src/guestfs.pod | 4 +- website/index.html.in | 1 + 8 files changed, 608 insertions(+), 402 deletions(-) create mode 100644 docs/guestfs-building.pod diff --git a/.gitignore b/.gitignore index c58898cdb..71ee3bb3a 100644 --- a/.gitignore +++ b/.gitignore @@ -143,6 +143,7 @@ Makefile.in /diff/stamp-virt-diff.pod /diff/virt-diff /diff/virt-diff.1 +/docs/guestfs-building.1 /docs/guestfs-faq.1 /docs/guestfs-hacking.1 /docs/guestfs-internals.1 @@ -151,6 +152,7 @@ Makefile.in /docs/guestfs-release-notes.1 /docs/guestfs-security.1 /docs/guestfs-testing.1 +/docs/stamp-guestfs-building.pod /docs/stamp-guestfs-faq.pod /docs/stamp-guestfs-hacking.pod /docs/stamp-guestfs-internals.pod diff --git a/README b/README index b3009a0f1..d63fe51e9 100644 --- a/README +++ b/README @@ -8,410 +8,15 @@ list: http://www.redhat.com/mailman/listinfo/libguestfs +To find out how to build libguestfs from source, read: -Requirements ----------------------------------------------------------------------- - -Running ./configure will check you have all the requirements installed -on your machine. - -Fedora/RHEL users: - - A useful tip is to run: - - yum-builddep libguestfs - or: - dnf builddep libguestfs - - which will install all build dependencies automatically. If that is - successful, you don't need to bother with the rest of this section. - -Debian/Ubuntu users: - - Use: - - apt-get build-dep libguestfs - - to install all build dependencies. If that doesn't work, take a - look at the Debian source package: - http://packages.debian.org/source/libguestfs - at the list of 'build-depends' and 'build-depends-indep', and - install everything listed there. - - If either of those techniques is successful, you don't need to - bother with the rest of this section. - -The full requirements are described below. - - R = Required - O = Optional -+==============+=============+===+=========================================+ -| Package name | Min.version | | Notes | -+==============+=============+===+=========================================+ -| Install as many packages listed in appliance/packagelist.in as possible. | -| This installs the disk management tools required by the appliance. The | -| list below is *additional* packages needed on the host. | -+--------------+-------------+---+-----------------------------------------+ -| qemu | 1.3.0 | R | 1.1 may work, but has broken virtio-scsi| -+--------------+-------------+---+-----------------------------------------+ -| qemu-img | 1.3.0 | R | >= 2.2.0 is required for virt-v2v but | -| | | | optional elsewhere | -+--------------+-------------+---+-----------------------------------------+ -| kernel | 2.6.34 | R | Make sure the following are enabled | -| | | | compiled in or as a module: | -| | | | - virtio-pci | -| | | | - virtio-serial | -| | | | - virtio-block | -| | | | - virtio-net | -+--------------+-------------+---+-----------------------------------------+ -| supermin | 5.1.0 | R | This is required on all distros. | -| | | | 'supermin' is the new name for | -| | | | 'febootstrap'. | -| | | | For alternatives, see: | -| | | | libguestfs.org/download/binaries/appliance/ -+--------------+-------------+---+-----------------------------------------+ -| glibc | | R | We use various glibc-isms. | -| | | | Also glibc provides XDR, rpcgen. | -+--------------+-------------+---+-----------------------------------------+ -| GCC or LLVM | | R | We use __attribute__((cleanup)). | -+--------------+-------------+---+-----------------------------------------+ -| Perl | | R | Various build and test programs need | -| | | | Perl. Not needed at runtime except if | -| | | | you need to run a handful of virt-* | -| | | | tools that are still written in Perl. | -+--------------+-------------+---+-----------------------------------------+ -| Pod::Man | | R | Part of Perl core. | -+--------------+-------------+---+-----------------------------------------+ -| Pod::Simple | | R | Part of Perl core. | -+--------------+-------------+---+-----------------------------------------+ -| OCaml | 3.11 |R/O| Required if compiling from git. | -| | | | Optional if compiling from tarball. | -| | | | To build generated files and OCaml bindings. -+--------------+-------------+---+-----------------------------------------+ -| findlib | |R/O| Required if compiling from git. | -| | | | Optional if compiling from tarball. | -| | | | To build generated files and OCaml bindings. -+--------------+-------------+---+-----------------------------------------+ -| autotools | |R/O| Required if compiling from git. | -| | | | Optional if compiling from tarball. | -| | | | Autotools-based build system. | -+--------------+-------------+---+-----------------------------------------+ -| cpio | | R | | -+--------------+-------------+---+-----------------------------------------+ -| gperf | | R | | -+--------------+-------------+---+-----------------------------------------+ -| flex | | R | flex & bison are required for virt- | -+--------------+-------------+---| builder. We could make these | -| bison | | R | optional but automakes makes it hard. | -+--------------+-------------+---+-----------------------------------------+ -| PCRE | | R | Perl-compatible Regular Expression lib. | -+--------------+-------------+---+-----------------------------------------+ -| genisoimage | | R | mkisofs may work. | -+--------------+-------------+---+-----------------------------------------+ -| libxml2 | | R | Popular XML library. | -+--------------+-------------+---+-----------------------------------------+ -| augeas | 1.0.0 | R | | -+--------------+-------------+---+-----------------------------------------+ -| xz | | R | Used to compress disk images. | -| | | | Used by virt-builder for compression. | -+--------------+-------------+---+-----------------------------------------+ -| yajl | 2.0.4 | R | JSON parser for parsing output of | -| | | | ldmtool and qemu-img info commands. | -+--------------+-------------+---+-----------------------------------------+ -| po4a | |R/O| Required if compiling from git. | -| | | | Optional if compiling from tarball. | -| | | | For localizing man pages. | -+--------------+-------------+---+-----------------------------------------+ -| hivex | 1.2.7 |R/O| Require if compiling from git. | -| | | | Windows Registry hive parser. | -+--------------+-------------+---+-----------------------------------------+ -| libmagic | | O | The library used by the 'file' command. | -+--------------+-------------+---+-----------------------------------------+ -| libvirt | | O | >= 0.10.2 is needed if you want to use | -| | | | libvirt to manage transient VMs. | -+--------------+-------------+---+-----------------------------------------+ -| xmllint | | O | Part of libxml2. Used for tests only. | -+--------------+-------------+---+-----------------------------------------+ -| libconfig | | O | Used to parse libguestfs's own config | -| | | | files eg. /etc/libguestfs-tools.conf. | -+--------------+-------------+---+-----------------------------------------+ -| libselinux | | O | Used by the libvirt backend to securely | -| | | | confine the appliance (sVirt). | -+--------------+-------------+---+-----------------------------------------+ -| db utils | | O | db_dump, db_load etc. Usually found in | -| | | | a package called db-utils, db4-utils, | -| | | | db4.X-utils, Berkeley DB utils, etc. | -+--------------+-------------+---+-----------------------------------------+ -| systemtap | | O | For userspace probes. | -+--------------+-------------+---+-----------------------------------------+ -| readline | | O | For nicer command line in guestfish. | -+--------------+-------------+---+-----------------------------------------+ -| acl | | O | Library (libacl) and programs for | -| | | | handling POSIX ACLs. | -+--------------+-------------+---+-----------------------------------------+ -| libcap | | O | Library (libcap) and programs for | -| | | | handling Linux capabilities. | -+--------------+-------------+---+-----------------------------------------+ -| libldm | | O | Library (libldm) and 'ldmtool' for | -| | | | handling Windows Dynamic Disks. | -+--------------+-------------+---+-----------------------------------------+ -| sd-journal | | O | systemd journal library | -+--------------+-------------+---+-----------------------------------------+ -| gdisk | | O | GPT disk support. | -+--------------+-------------+---+-----------------------------------------+ -| netpbm | | O | Render icons from guests. | -+--------------+-------------+---+-----------------------------------------+ -| icoutils | | O | Render icons from Windows guests. | -+--------------+-------------+---+-----------------------------------------+ -| Expect | | O | Perl module used to test virt-rescue. | -+--------------+-------------+---+-----------------------------------------+ -| FUSE | | O | fusermount, libfuse, and kernel module | -| | | | are all needed if you want guestmount | -| | | | and/or 'mount-local' support. | -+--------------+-------------+---+-----------------------------------------+ -| static glibc | | O | Used for testing only. | -+--------------+-------------+---+-----------------------------------------+ -| qemu-nbd | | O | Used for testing only. | -+--------------+-------------+---+-----------------------------------------+ -| uml_mkcow | | O | For the UML backend. | -+--------------+-------------+---+-----------------------------------------+ -| curl | | O | Used by virt-builder for downloads | -+--------------+-------------+---+-----------------------------------------+ -| gpg | | O | Used by virt-builder for digital | -| | | | signatures | -+--------------+-------------+---+-----------------------------------------+ -| liblzma | | O | Can be used by virt-builder for fast | -| | | | uncompression of templates. | -+--------------+-------------+---+-----------------------------------------+ -| gtk2 | 2.24 | O | Used by virt-p2v user interface. | -+--------------+-------------+---+-----------------------------------------+ -| zip, unzip | | O | Used by virt-v2v for OVA files. | -+--------------+-------------+---+-----------------------------------------+ -| python-evtx | | O | Used by virt-log to parse Windows | -| | | | Event Log files. | -+--------------+-------------+---+-----------------------------------------+ -| ocaml-gettext| | O | For localizing OCaml virt-* tools. | -+--------------+-------------+---+-----------------------------------------+ -| Module::Build| 0.19 | O | To build the Perl bindings. | -+--------------+-------------+---+-----------------------------------------+ -| Python | 2.2 | O | For the Python bindings. | -+--------------+-------------+---+-----------------------------------------+ -| Ruby | | O | >= 1.9 is better than 1.8. | -+--------------+-------------+---+-----------------------------------------+ -| rake | | O | For the Ruby bindings. | -+--------------+-------------+---+-----------------------------------------+ -| rubygem-minitest | O | For the Ruby bindings. | -+--------------+-------------+---+-----------------------------------------+ -| Java | 1.6 | O | Java + JNI + jpackage-utils are needed | -| | | | for the Java bindings. | -+--------------+-------------+---+-----------------------------------------+ -| GHC | | O | For the Haskell bindings. | -+--------------+-------------+---+-----------------------------------------+ -| PHP | | O | For the PHP bindings. | -+--------------+-------------+---+-----------------------------------------+ -| phpize | | O | For the PHP bindings. | -+--------------+-------------+---+-----------------------------------------+ -| glib2 | | O | For the GObject bindings. | -+--------------+-------------+---+-----------------------------------------+ -| gobject-introspection | O | For the GObject bindings. | -+--------------+-------------+---+-----------------------------------------+ -| gjs | | O | For testing the GObject bindings. | -+--------------+-------------+---+-----------------------------------------+ -| LUA | | O | For the LUA bindings. | -+--------------+-------------+---+-----------------------------------------+ -| Erlang | | O | For the Erlang bindings. | -+--------------+-------------+---+-----------------------------------------+ -| erl_interface| | O | For the Erlang bindings. | -+--------------+-------------+---+-----------------------------------------+ -| golang | 1.1.1 | O | For the Go bindings. | -+--------------+-------------+---+-----------------------------------------+ -| valgrind | | O | For testing for memory problems. | -+--------------+-------------+---+-----------------------------------------+ -| Sys::Virt | | O | Perl bindings for libvirt. | -+--------------+-------------+---+-----------------------------------------+ -| libvirt-python | O | For testing Python libvirt/libguestfs | -| | | | interactions. | -+--------------+-------------+---+-----------------------------------------+ -| Win::Hivex | | O | Perl bindings for hivex. | -+--------------+-------------+---+-----------------------------------------+ -| Pod::Usage | | O | Perl module used by tests. | -+--------------+-------------+---+-----------------------------------------+ -| Test::More | | O | Perl module used by tests. | -+--------------+-------------+---+-----------------------------------------+ -| perl-libintl | | O | Perl module for localization. | -+--------------+-------------+---+-----------------------------------------+ -| bash-completion | O | For tab-completion of commands in bash. | -+--------------+-------------+---+-----------------------------------------+ -| ocaml-ounit | 2.0.0 | O | For the tests of the common OCaml | -| | | | modules. | -+--------------+-------------+---+-----------------------------------------+ -| ocaml-libvirt| 0.6.1.5 | O | For building the virt-v2v test harness. | -+==============+=============+===+=========================================+ - R = Required - O = Optional - - -Building ----------------------------------------------------------------------- - -Build the daemon, library and root filesystem: - - building from tarball building from git - --------------------- ----------------- - ./configure ./autogen.sh - make make - -Run the tests: - - make check - -Also: - - make check-valgrind - -runs a subset of the test suite under valgrind (requires valgrind to -be installed obviously). - - make check-all - -runs check-valgrind + even more tests, but these require that you have -some libvirt guests installed, that these guests' disks are accessible -by the current user, and these tests may fail for other reasons which -are not necessarily because of real problems. - - make help - -lists all 'make' targets. - -You may install the library by running the following command as root. -However *most users should probably not do this*. Instead, './run' -the programs from the build directory as described below. - - make install - -Distro packagers should use this instead: - - make INSTALLDIRS=vendor [DESTDIR=...] install - -You can run guestfish, guestmount and the virt tools without needing -to install, using the "./run" script in the top directory. This -script sets up some environment variables. For example: - - ./run guestfish [usual guestfish args ...] - - ./run virt-inspector [usual virt-inspector args ...] - -If you are already in the fish/ subdirectory, then the following -command will also work: - - ../run guestfish [...] - -The ./run script adds every libguestfs binary to the $PATH, so the -above example runs guestfish from the build directory (not the -globally installed guestfish if there is one). - -You can also run the C programs under valgrind like this: - - ./run valgrind [valgrind opts...] virt-cat [virt-cat opts...] - -or under gdb: - - ./run gdb --args virt-cat [virt-cat opts...] - -This also works with sudo (eg. if you need root access for libvirt or -to access a block device): - - sudo ./run virt-cat -d LinuxGuest /etc/passwd - - -qemu ----------------------------------------------------------------------- - -By far the most common problem is with broken or incompatible -qemu releases. - -Different versions of qemu have problems booting the appliance for -different reasons. This varies between versions of qemu, and Linux -distributions which add their own patches. - -If you find a problem, you could try using your own qemu built from -source (qemu is very easy to build from source), with a 'qemu -wrapper'. Qemu wrappers are described in the guestfs(3) manpage. - - -Note on using KVM ----------------------------------------------------------------------- - -By default the configure script will look for qemu-kvm (KVM support). -You will need a reasonably recent processor for this to work. KVM is -much faster than using plain Qemu. - -You may also need to enable KVM support for non-root users, by following -these instructions: - - http://www.linux-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non-privileged_user.3F - -On some systems, this will work too: - - chmod 0666 /dev/kvm - -On some systems, the chmod will not survive a reboot, and you will -need to make edits to the udev configuration. - - -Mirroring tip ----------------------------------------------------------------------- - -On my machines I can usually rebuild the appliance in around 3 -minutes. If it takes much longer for you, use a local distro mirror -or squid. - -To use squid to cache yum downloads, read this first: -https://lists.dulug.duke.edu/pipermail/yum/2006-August/009041.html -(In brief, because yum chooses random mirrors each time, squid doesn't -work very well with default yum configuration. To get around this, -choose a Fedora mirror which is close to you, set this with -'./configure --with-mirror=[...]', and then proxy the whole lot -through squid by setting http_proxy environment variable). - -You will also need to substantially increase the squid configuration -limits: -http://fedoraproject.org/wiki/Using_Mock_to_test_package_builds#Using_Squid_to_Speed_Up_Mock_package_downloads - - -Porting to other Linux distros / non-Linux ----------------------------------------------------------------------- - -libguestfs itself should be fairly portable to other Linux -distributions. Non-Linux ports are trickier, but we will accept -patches if they aren't too invasive. - -The main porting issues are with the dependencies needed to build the -appliance. You will need to port supermin first -(http://people.redhat.com/~rjones/supermin/). - - -Note on using clang (from LLVM) instead of GCC ----------------------------------------------------------------------- - - export CC=clang - ./configure --disable-probes - make - -SystemTap/DTrace-style userspace probe points don't work under the -clang compiler, which is why you may need to disable them. - -Don't enable GCC warnings (ie. *don't* use -'./configure --enable-gcc-warnings'). - - -Copyright and license information ----------------------------------------------------------------------- + docs/guestfs-building.pod + http://libguestfs.org/guestfs-building.1.html + man docs/guestfs-building.1 Copyright (C) 2009-2016 Red Hat Inc. The library is distributed under the LGPLv2+. The programs are distributed under the GPLv2+. Please see the files COPYING and -COPYING.LIB for full license information. - -The examples are under a very liberal license. +COPYING.LIB for full license information. The examples are under a +very liberal license. diff --git a/docs/Makefile.am b/docs/Makefile.am index 8b2e2451b..f880e72e8 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -18,6 +18,7 @@ include $(top_srcdir)/subdir-rules.mk EXTRA_DIST = \ + guestfs-building.pod \ guestfs-faq.pod \ guestfs-hacking.pod \ guestfs-internals.pod \ @@ -29,6 +30,7 @@ EXTRA_DIST = \ README CLEANFILES = \ + guestfs-building.1 \ guestfs-faq.1 \ guestfs-hacking.1 \ guestfs-internals.1 \ @@ -37,6 +39,7 @@ CLEANFILES = \ guestfs-release-notes.1 \ guestfs-security.1 \ guestfs-testing.1 \ + stamp-guestfs-building.pod \ stamp-guestfs-faq.pod \ stamp-guestfs-hacking.pod \ stamp-guestfs-internals.pod \ @@ -47,6 +50,7 @@ CLEANFILES = \ stamp-guestfs-testing.pod man_MANS = \ + guestfs-building.1 \ guestfs-faq.1 \ guestfs-hacking.1 \ guestfs-internals.1 \ @@ -56,6 +60,7 @@ man_MANS = \ guestfs-security.1 \ guestfs-testing.1 noinst_DATA = \ + $(top_builddir)/website/guestfs-building.1.html \ $(top_builddir)/website/guestfs-faq.1.html \ $(top_builddir)/website/guestfs-hacking.1.html \ $(top_builddir)/website/guestfs-internals.1.html \ @@ -65,6 +70,17 @@ noinst_DATA = \ $(top_builddir)/website/guestfs-security.1.html \ $(top_builddir)/website/guestfs-testing.1.html +guestfs-building.1 $(top_builddir)/website/guestfs-building.1.html: stamp-guestfs-building.pod + +stamp-guestfs-building.pod: guestfs-building.pod + $(PODWRAPPER) \ + --section 1 \ + --man guestfs-building.1 \ + --html $(top_builddir)/website/guestfs-building.1.html \ + --license LGPLv2+ \ + $< + touch $@ + guestfs-faq.1 $(top_builddir)/website/guestfs-faq.1.html: stamp-guestfs-faq.pod stamp-guestfs-faq.pod: guestfs-faq.pod diff --git a/docs/guestfs-building.pod b/docs/guestfs-building.pod new file mode 100644 index 000000000..840a7f952 --- /dev/null +++ b/docs/guestfs-building.pod @@ -0,0 +1,578 @@ +=head1 NAME + +guestfs-building - How to build libguestfs from source + +=head1 DESCRIPTION + +This manual page describes how to build libguestfs from source. + +The main steps are: + +=over 4 + +=item * + +Install the requirements. + +=item * + +Build, either from the git repository or from a tarball. + +=item * + +Run the tests. + +=item * + +Run the tools from the source directory, or install. + +=back + +=head1 REQUIREMENTS + +=head2 Short cut for Fedora or Red Hat Enterprise Linux (RHEL) users + +On Fedora, use L to install all the requirements: + + dnf builddep libguestfs + +On systems still using L, do: + + yum-builddep libguestfs + +=head2 Short cut for Debian or Ubuntu users + +Use APT to install all the requirements: + + apt-get build-dep libguestfs + +If that command doesn't work, take a look at the Debian source package +L, at the list of +C and C, and install everything +listed there. + +=head2 Full list of requirements + +=over 4 + +=item F + +Install as many package names found in this file as possible. (It is +not strictly required to install all of them). + +=item qemu E 1.3.0 + +I. + +=item qemu-img E 1.3.0 + +I. Virt-p2v and virt-v2v requires qemu-img E 2.2.0. + +=item kernel E 2.6.34 + +I. The following features must be enabled: +C, C, C, C. + +=item supermin E 5.1.0 + +I. For alternatives, see L +below. + +=item glibc + +I. We use various glibc-isms, and glibc also provides XDR +libraries and the C tool. + +=item Gcc or Clang + +I. We use C<__attribute__((cleanup))> which is a GCC +extension also supported by Clang. + +=item Perl + +I. Various build steps and tests are written in Perl. Perl +is not needed at runtime except if you need to run a small number of +virt tools which are still written in Perl. + +=item Perl C + +=item Perl C + +I. Part of Perl core. + +=item OCaml E 3.11 + +=item OCaml findlib + +I if compiling from git. +Optional (but recommended) if compiling from tarball. + +=item autoconf + +=item automake + +I if compiling from git. +Optional if compiling from tarball. + +=item cpio + +I. + +=item gperf + +I. + +=item flex + +=item bison + +I. + +=item Perl-compatible Regular Expressions (PCRE) library + +I. + +=item genisoimage + +I. + +=item libxml2 + +I. + +=item augeas E 1.0.0 + +I. + +=item xz + +I. + +=item yajl E 2.0.4 + +I. + +=item po4a + +I if compiling from git. +Optional if compiling from tarball. + +=item hivex E 1.2.7 + +I if compiling from git, and highly recommended otherwise. +Various core features will be disabled if hivex is not available. + +=item libmagic + +Optional. This is the library used by the L command. + +=item libvirt E 0.10.2 + +Optional. Always use the latest possible version of libvirt. + +=item xmllint + +Optional. Used only for tests. + +=item libconfig + +Optional. Used to parse libguestfs's own config files, +eg. F. + +=item libselinux + +Optional. Used by the L to +securely confine the appliance (sVirt). + +=item Berkeley DB utils (db_dump, db_load, etc) + +Optional. Usually found in a package called C, +C, C etc. + +=item systemtap + +Optional. For userspace probes. + +=item readline + +Optional. For nicer command line editing in L. + +=item acl + +Optional. Library and programs for handling POSIX ACLs. + +=item libcap + +Optional. Library and programs for handling Linux capabilities. + +=item libldm + +Optional. Library and L for handling +Windows Dynamic Disks. + +=item sd-journal + +Optional. Library for accessing systemd journals. + +=item gdisk + +Optional. GPT disk support. + +=item netpbm + +Optional. Render icons from guests. + +=item icoutils + +Optional. Render icons from Windows guests. + +=item Perl C + +Optional. Perl module used to test L. + +=item FUSE + +Optional. L, libfuse and kernel module are all needed +if you want L and/or L +support. + +=item static glibc + +Optional. Used only for testing. + +=item qemu-nbd + +Optional. Used for testing, and by virt-p2v. + +=item uml_mkcow + +Optional. For the L. + +=item curl + +Optional. Used by virt-builder for downloads. + +=item gpg + +Optional. Used by virt-builder for checking digital signatures. + +=item liblzma + +Optional. If available, virt-builder will use this library +for fast, parallel uncompression of templates. + +=item gtk2 E 2.24 + +Optional. Used by the virt-p2v user interface. + +=item zip + +=item unzip + +Optional. Used by virt-v2v to handle OVA files. + +=item python-evtx + +Optional. Used by L to parse Windows Event Log files. + +=item OCaml gettext + +Optional. For localizing OCaml virt tools. + +=item ocaml-ounit E 2.0.0 + +Optional. For testing the common OCaml modules. + +=item ocaml-libvirt E 0.6.1.5 + +Optional. For building the optional virt-v2v test harness. + +=item Perl C E 0.19 + +=item Perl C + +Optional. Used to build and test the Perl bindings. + +=item Python E 2.2 + +Optional. Used to build the Python bindings. For building +Python 2 or Python 3 bindings, see +L below. + +=item Ruby + +=item rake + +=item rubygem-minitest + +Optional. Used to build the Ruby bindings. + +=item Java E 1.6 + +Optional. Java, JNI and jpackage-utils are needed for building Java +bindings. + +=item GHC + +Optional. Used to build the Haskell bindings. + +=item PHP + +=item phpize + +Optional. Used to build the PHP bindings. + +=item glib2 + +=item gobject-introspection + +=item gjs + +Optional. Used to build and test the GObject bindings. + +=item LUA + +Optional. Used to build the LUA bindings. + +=item Erlang + +=item erl_interface + +Optional. Used to build the Erlang bindings. + +=item golang E 1.1.1 + +Optional. Used to build the Go bindings. + +=item valgrind + +Optional. For testing memory problems. + +=item Perl C + +Optional. + +=item libvirt-python + +Optional. For testing Python libvirt/libguestfs interactions. + +=item Perl C + +Optional. Used by the L tool. + +=item Perl C + +Optional. Used by some Perl virt tools. + +=item Perl C + +Optional. + +=item bash-completion + +Optional. For tab-completion of commands in bash. + +=back + +=head1 BUILDING FROM GIT + + git clone https://github.com/libguestfs/libguestfs + cd libguestfs + ./autogen.sh + make + +=head1 BUILDING FROM TARBALLS + +Download and unpack the tarball. + + cd libguestfs-1.xx.yy + ./configure + make + +=head1 RUNNING THE TESTS + +To sanity check that the build worked, do: + + make quickcheck + +To run the basic tests, do: + + make check + +There are many more tests you can run. See L +for details. + +=head1 INSTALLING + +B!> You'll end up with conflicting versions +of libguestfs installed, and this causes constant headaches for users. + +Distro packagers can use: + + make INSTALLDIRS=vendor DESTDIR=[temp-build-dir] install + +You can run L, L and the virt tools +without needing to install, using the F<./run> script in the top +directory. This script sets up some environment variables. For +example: + + ./run guestfish [usual guestfish args ...] + + ./run virt-inspector [usual virt-inspector args ...] + +If you are already in the F subdirectory, then the following +command will also work: + + ../run guestfish [...] + +The F<./run> script adds every libguestfs binary to the C<$PATH>, so +the above example runs guestfish from the build directory (not the +globally installed guestfish if there is one). + +You can also run the C programs under valgrind like this: + + ./run valgrind [valgrind opts...] virt-cat [virt-cat opts...] + +or under gdb: + + ./run gdb --args virt-cat [virt-cat opts...] + +This also works with sudo (eg. if you need root access for libvirt or +to access a block device): + + sudo ./run virt-cat -d LinuxGuest /etc/passwd + +=head1 NOTES ABOUT QEMU AND KVM + +A common problem is with broken or incompatible qemu releases. + +Different versions of qemu have problems booting the appliance for +different reasons. This varies between versions of qemu, and Linux +distributions which add their own patches. + +If you find a problem, you could try using your own qemu built from +source (qemu is very easy to build from source), with a "qemu +wrapper". See L. + +By default the configure script will look for qemu-kvm (KVM support). +KVM is much faster than using plain qemu. + +You may also need to enable KVM support for non-root users, by +following these instructions: +L + +On some systems, this will work too: + + chmod 0666 /dev/kvm + +On some systems, the chmod will not survive a reboot, and you will +need to make edits to the udev configuration. + +=head1 USING CLANG (LLVM) INSTEAD OF GCC + + export CC=clang + ./configure --disable-probes + make + +SystemTap/DTrace-style userspace probe points don't work under the +Clang compiler, which is why you may need to disable them. + +Don't enable GCC warnings (ie. I use +C<./configure --enable-gcc-warnings>). + +=head1 USING A PREBUILT BINARY APPLIANCE + +To understand what the libguestfs appliance means, see +L. + +If you are using non-Linux, or a Linux distribution that does not have +L support, or simply if you don't want to build your own +libguestfs appliance, then you can use one of the prebuilt binary +appliances that we supply: +L + +Build libguestfs like this: + + ./configure --disable-appliance --disable-daemon + make + +Set C<$LIBGUESTFS_PATH> to the path where you unpacked the appliance +tarball, eg: + + export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance + +and run the libguestfs programs and virt tools in the normal way, +eg. using the F<./run> script (see above). + +=head1 BUILDING PYTHON 2 AND PYTHON 3 BINDINGS + +The F<./configure> script detects the currently installed version of +Python using whatever program is called C in the current +C<$PATH>. Libguestfs will build Python 2 or Python 3 bindings as +appropriate. + +You can override this behaviour by specifying an alternate Python +binary, eg: + + PYTHON=/usr/bin/python3 ./configure + +To build parallel Python 2 and Python 3 bindings, you will need to +build libguestfs twice. The second time, you can disable all the +other bindings and tools and just build the Python bindings. See the +Fedora spec file (see below) for a complete example of how to do this. + +=head1 BUILDING A PACKAGE FOR FEDORA + +The Fedora spec file is stored under: +L + +Libguestfs is built in Fedora using the ordinary Fedora build system +(Koji). + +=head1 BUILDING A PACKAGE FOR RED HAT ENTERPRISE LINUX + +Red Hat Enterprise Linux (RHEL) builds of libguestfs are heavily +patched. There are broadly two types of patches we apply: + +=over 4 + +=item * + +We disable many features that we do not wish to support for RHEL +customers. For example, the "libguestfs live" feature is disabled. + +=item * + +We backport upstream features. + +=back + +The patches we apply to RHEL releases are available publically in the +upstream git repository, in a branch called C + +For example, the RHEL 7.3 patches are available here: +L + +The sources and spec files for RHEL versions of libguestfs are +available on L + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009-2016 Red Hat Inc. diff --git a/po-docs/language.mk b/po-docs/language.mk index 9319f866b..f7a44f3a4 100644 --- a/po-docs/language.mk +++ b/po-docs/language.mk @@ -29,6 +29,7 @@ CLEANFILES += *.pl MANPAGES = \ guestfish.1 \ guestfs.3 \ + guestfs-building.1 \ guestfs-erlang.3 \ guestfs-examples.3 \ guestfs-faq.1 \ diff --git a/po-docs/podfiles b/po-docs/podfiles index 58c09f6b0..97e2d4faf 100644 --- a/po-docs/podfiles +++ b/po-docs/podfiles @@ -13,6 +13,7 @@ ../df/virt-df.pod ../dib/virt-dib.pod ../diff/virt-diff.pod +../docs/guestfs-building.pod ../docs/guestfs-faq.pod ../docs/guestfs-hacking.pod ../docs/guestfs-internals.pod diff --git a/src/guestfs.pod b/src/guestfs.pod index 4b451bd5b..a4d7d5751 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -40,7 +40,8 @@ For tips and recipes, see L. If you are having performance problems, read L. To help test libguestfs, read -L and L. To contribute +L and L. To build +libguestfs from source, read L. To contribute code to libguestfs, see L. To find out how libguestfs works, see L. @@ -3501,6 +3502,7 @@ L, L. Other libguestfs topics: +L, L, L, L, diff --git a/website/index.html.in b/website/index.html.in index 6db0525b3..4f40f6c3d 100644 --- a/website/index.html.in +++ b/website/index.html.in @@ -139,6 +139,7 @@ For developers: README, TODO, FAQ, +guestfs-building(1), guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),