1guestfs-building(1) Virtualization Support guestfs-building(1)
2
6 guestfs-building - How to build libguestfs from source
7
9 This manual page describes how to build libguestfs from source.
10 The main steps are:
12 · Install the requirements.
14 · Build, either from the git repository or from a tarball.
16 · Run the tests.
18 · Run the tools from the source directory, or install.
20
22 Short cut for Fedora or Red Hat Enterprise Linux (RHEL) users
23 On Fedora, use dnf(8) to install all the requirements:
24 dnf builddep libguestfs
26 dnf install autoconf automake libtool gettext-devel
27 On systems still using yum(8), do:
29 yum-builddep libguestfs
31 yum install autoconf automake libtool gettext-devel
32 Short cut for Debian or Ubuntu users
34 Use APT to install all the requirements:
35 apt-get build-dep libguestfs
37 apt-get install autoconf automake libtool-bin gettext
38 If that command doesn't work, take a look at the Debian source package
40 http://packages.debian.org/source/libguestfs, at the list of
41 "build-depends" and "build-depends-indep", and install everything
42 listed there.
43 Full list of requirements
45 appliance/packagelist.in
46 Install as many package names found in this file as possible. (It
47 is not strictly required to install all of them).
48 Note: If you build libguestfs followed by installing appliance
50 packages, the build will not pick them up automatically, even if
51 you do "make clean". You have to do this command to clean the old
52 supermin appliance and force a new one to be prepared:
53 make -C appliance clean-supermin-appliance
55 qemu ≥ 1.3.0
57 Required.
58 qemu-img ≥ 1.3.0
60 Required.
61 kernel ≥ 2.6.34
63 Required. The following features must be enabled: "virtio-pci",
64 "virtio-serial", "virtio-block", "virtio-net".
65 supermin ≥ 5.1.18
67 Required. For alternatives, see "USING A PREBUILT BINARY
68 APPLIANCE" below.
69 glibc
71 Required. We use the custom printf formatters extension of glibc
72 (see "DAEMON CUSTOM PRINTF FORMATTERS" in guestfs-hacking(1)).
73 XDR (tirpc, glibc or other)
75 Required. We use the XDR implementation from "<rpc/xdr.h>", which
76 may come from glibc, tirpc or another library.
77 The "rpcgen" tool is optional, except if you want to compile from
79 git and/or patch libguestfs with new APIs.
80 Gcc or Clang
82 Required. We use "__attribute__((cleanup))" which is a GCC
83 extension also supported by Clang.
84 Perl
86 Required. Various build steps and tests are written in Perl. Perl
87 is not needed at runtime except if you need to run a small number
88 of virt tools which are still written in Perl.
89 Perl "Pod::Man"
91 Perl "Pod::Simple"
92 Required. Part of Perl core.
93 OCaml ≥ 4.01
95 OCaml findlib
96 Required.
97 autoconf
99 automake
100 gettext
101 Required if compiling from git. Optional if compiling from
102 tarball.
103 cpio
105 Required.
106 gperf
108 Required.
109 flex
111 bison
112 Required.
113 Perl-compatible Regular Expressions (PCRE) library
115 Required.
116 genisoimage
118 Required.
119 libxml2
121 Required.
122 ncurses
124 Required.
125 augeas ≥ 1.2.0
127 Required.
128 xz Required.
130 Jansson ≥ 2.7
132 Required.
133 po4a
135 Required if compiling from git. Optional if compiling from
136 tarball.
137 hivex ≥ 1.2.7
139 ocaml-hivex
140 Required. ocaml-hivex is the OCaml binding for hivex, which is
141 required when building the daemon.
142 libmagic
144 Required. This is the library used by the file(1) command.
145 libvirt ≥ 0.10.2
147 Optional. Always use the latest possible version of libvirt.
148 xmllint
150 Optional. Used only for tests.
151 libconfig
153 Optional. Used to parse libguestfs’s own config files, eg.
154 /etc/libguestfs-tools.conf.
155 libselinux
157 Optional. Used by the libvirt backend to securely confine the
158 appliance (sVirt).
159 Berkeley DB utils (db_dump, db_load, etc)
161 Optional. Usually found in a package called "db-utils",
162 "db4-utils", "db4.X-utils" etc.
163 systemtap
165 Optional. For userspace probes.
166 readline
168 Optional. For nicer command line editing in guestfish(1).
169 acl Optional. Library and programs for handling POSIX ACLs.
171 libcap
173 Optional. Library and programs for handling Linux capabilities.
174 libldm
176 Optional. Library and ldmtool(1) for handling Windows Dynamic
177 Disks.
178 sd-journal
180 Optional. Library for accessing systemd journals.
181 gdisk
183 Optional. GPT disk support.
184 netpbm
186 Optional. Render icons from guests.
187 icoutils
189 Optional. Render icons from Windows guests.
190 Perl "Expect"
192 Optional. Perl module used to test virt-rescue(1).
193 FUSE
195 Optional. fusermount(1), libfuse and kernel module are all needed
196 if you want guestmount(1) and/or mount-local support.
197 static glibc
199 Optional. Used only for testing.
200 qemu-nbd
202 nbdkit ≥ 1.12
203 Optional. qemu-nbd is used for testing.
204 uml_mkcow
206 Optional. For the UML backend.
207 curl
209 Optional. Used by virt-builder for downloads.
210 GNU Privacy Guard (GnuPG, gpg) v1 or v2
212 Optional. Used by virt-builder for checking digital signatures.
213 liblzma
215 Optional. If available, virt-builder will use this library for
216 fast, parallel uncompression of templates.
217 python-evtx
219 Optional. Used by virt-log(1) to parse Windows Event Log files.
220 OCaml gettext
222 Optional. For localizing OCaml virt tools.
223 ocaml-ounit ≥ 2.0.0
225 Optional. For testing the common OCaml modules.
226 Perl "Module::Build" ≥ 0.19
228 Perl "Test::More"
229 Optional. Used to build and test the Perl bindings.
230 Python ≥ 2.7
232 Optional. Used to build the Python bindings. For building Python
233 2 or Python 3 bindings, see "BUILDING PYTHON 2 AND PYTHON 3
234 BINDINGS" below.
235 Python "unittest"
237 Optional. Used to run the Python testsuite.
238 Ruby
240 rake
241 rubygem-minitest
242 rubygem-rdoc
243 Optional. Used to build the Ruby bindings.
244 Java ≥ 1.6
246 Optional. Java, JNI and jpackage-utils are needed for building
247 Java bindings.
248 GHC Optional. Used to build the Haskell bindings.
250 PHP
252 phpize
253 Optional. Used to build the PHP bindings.
254 glib2
256 gobject-introspection
257 gjs Optional. Used to build and test the GObject bindings.
258 vala
260 Optional. Used to build the Vala bindings.
261 LUA Optional. Used to build the LUA bindings.
263 Erlang
265 erl_interface
266 Optional. Used to build the Erlang bindings.
267 golang ≥ 1.1.1
269 Optional. Used to build the Go bindings.
270 valgrind
272 Optional. For testing memory problems.
273 Perl "Sys::Virt"
275 Optional.
276 libvirt-python
278 Optional. For testing Python libvirt/libguestfs interactions.
279 Perl "Win::Hivex"
281 Optional. Used by the virt-win-reg(1) tool.
282 Perl "Pod::Usage"
284 Optional. Used by some Perl virt tools.
285 Perl "libintl"
287 Optional.
288 bash-completion
290 Optional. For tab-completion of commands in bash.
291 libtsk
293 Optional. Library for filesystem forensics analysis.
294 yara
296 Optional. Tool for categorizing files based on their content.
297
299 You will need to install additional dependencies "autoconf",
300 "automake", "gettext", OCaml findlib and po4a when building from git.
301 git clone https://github.com/libguestfs/libguestfs
303 cd libguestfs
304 git submodule update --init
305 CFLAGS=-fPIC ./autogen.sh
306 make
307
309 Tarballs are downloaded from http://download.libguestfs.org/. Stable
310 tarballs are signed with the GnuPG key for "rich@annexia.org", see
311 https://pgp.mit.edu/pks/lookup?op=vindex&search=0x91738F73E1B768A0.
312 The fingerprint is "F777 4FB1 AD07 4A7E 8C87 67EA 9173 8F73 E1B7 68A0".
313 Download and unpack the tarball.
315 cd libguestfs-1.xx.yy
317 ./configure
318 make
319
321 DO NOT run the tests as root! Libguestfs can be built and tested as
322 non-root. Running the tests as root could even be dangerous, don't do
323 it.
324 To sanity check that the build worked, do:
326 make quickcheck
328 To run the basic tests, do:
330 make check
332 There are many more tests you can run. See guestfs-hacking(1) for
334 details.
335
337 DO NOT use "make install"! You'll end up with conflicting versions of
338 libguestfs installed, and this causes constant headaches for users.
339 See the next section for how to use the ./run script instead.
340 Distro packagers can use:
342 make INSTALLDIRS=vendor DESTDIR=[temp-build-dir] install
344
346 You can run guestfish(1), guestmount(1) and the virt tools without
347 needing to install them by using the ./run script in the top directory.
348 This script works by setting several environment variables.
349 For example:
351 ./run guestfish [usual guestfish args ...]
353 ./run virt-inspector [usual virt-inspector args ...]
355 The ./run script adds every libguestfs binary to the $PATH, so the
357 above examples run guestfish and virt-inspector from the build
358 directory (not the globally installed guestfish if there is one).
359 You can use the script from any directory. If you wanted to run your
361 own libguestfs-using program, then the following command will also
362 work:
363 /path/to/libguestfs/run ./my_program [...]
365 You can also run the C programs under valgrind like this:
367 ./run valgrind [valgrind opts...] virt-cat [virt-cat opts...]
369 or under gdb:
371 ./run gdb --args virt-cat [virt-cat opts...]
373 This also works with sudo (eg. if you need root access for libvirt or
375 to access a block device):
376 sudo ./run virt-cat -d LinuxGuest /etc/passwd
378 To set environment variables, you can either do:
380 LIBGUESTFS_HV=/my/qemu ./run guestfish
382 or:
384 ./run env LIBGUESTFS_HV=/my/qemu guestfish
386
388 Files in the top source directory that begin with the prefix local* are
389 ignored by git. These files can contain local configuration or scripts
390 that you need to build libguestfs.
391 I have a file called localconfigure which is a simple wrapper around
393 autogen.sh containing local configure customizations that I need. It
394 looks like this:
395 . localenv
397 ./autogen.sh \
398 -C \
399 --enable-werror \
400 "$@"
401 So I can use this to build libguestfs:
403 ./localconfigure && make
405 If there is a file in the top build directory called localenv, then it
407 will be sourced by "make". This file can contain any local environment
408 variables needed, eg. for skipping tests:
409 # Use an alternate python binary.
411 export PYTHON=python3
412 # Skip this test, it is broken.
413 export SKIP_TEST_BTRFS_FSCK=1
414 Note that localenv is included by the top Makefile (so it’s a Makefile
416 fragment). But if it is also sourced by your localconfigure script
417 then it is used as a shell script.
418
420 There are many "./configure" options. Use:
421 ./configure --help
423 to list them all. This section covers some of the more important ones.
425 --disable-appliance --disable-daemon
427 See "USING A PREBUILT BINARY APPLIANCE" below.
428 --disable-erlang
430 --disable-gobject
431 --disable-golang
432 --disable-haskell
433 --disable-lua
434 --disable-ocaml
435 --disable-perl
436 --disable-php
437 --disable-python
438 --disable-ruby
439 Disable specific language bindings, even if "./configure" finds all
440 the necessary libraries are installed so that they could be
441 compiled.
442 Note that disabling OCaml (bindings) or Perl will have the knock-on
444 effect of disabling parts of the test suite and some tools.
445 OCaml is required to build libguestfs and this requirement cannot
447 be removed. Using --disable-ocaml only disables the bindings and
448 OCaml tools.
449 --disable-fuse
451 Disable FUSE support in the API and the guestmount(1) tool.
452 --disable-gnulib-tests
454 On some platforms the GNUlib test suite can be flaky. This
455 disables it, since errors in the GNUlib test suite are often not
456 important.
457 --disable-static
459 Don’t build a static linked version of the libguestfs library.
460 --enable-install-daemon
462 Normally guestfsd(8) is not installed by "make install", since that
463 wouldn't be useful (instead it is "installed" inside the supermin
464 appliance). However if packagers are building "libguestfs live"
465 then they should use this option.
466 --enable-werror
468 This turns compiler warnings into errors (ie. "-Werror"). Use this
469 for development, especially when submitting patches. It should
470 generally not be used for production or distro builds.
471 --with-default-backend=libvirt
473 This controls the default method that libguestfs uses to run qemu
474 (see "BACKEND" in guestfs(3)). If not specified, the default
475 backend is "direct", which means libguestfs runs qemu directly.
476 Fedora and Red Hat Enterprise Linux (RHEL) ≥ 7 use this flag to
478 change the default backend to "libvirt", because (especially in
479 RHEL) the policy is not to allow any program to run qemu except via
480 libvirt.
481 Note that despite this setting, all backends are built into
483 libguestfs, and you can override the backend at runtime by setting
484 the $LIBGUESTFS_BACKEND environment variable (or using API
485 methods).
486 --with-distro=REDHAT|DEBIAN|...
488 Libguestfs needs to know which Linux distro is in use so it can
489 choose package names for the appliance correctly (see for example
490 appliance/packagelist.in). It normally does this automatically.
491 However if you can building or packaging libguestfs on a new distro
493 then you can use --with-distro to specify that the distro is
494 similar to an existing one (eg. --with-distro=REDHAT if the distro
495 is a new Red Hat or CentOS derivative).
496 Note that if your distro is completely new then it may still
498 require upstream modifications.
499 --with-extra="distroname=version,libvirt,..."
501 --with-extra="local"
502 This option controls the "extra" field returned by
503 "guestfs_version" in guestfs(3) and also printed by virt tools'
504 --version option. It is a free text field, but a good idea is to
505 encode a comma-separated list of facts such as the distro name and
506 version, whether libvirt is the default backend, and anything else
507 that may help with debugging problems raised by users.
508 For custom and/or local builds, this can be set to "local" to
510 indicate this is not a distro build.
511 --without-libvirt
513 Compile libguestfs without libvirt support, even if libvirt
514 development libraries are installed.
515 --with-qemu="bin1 bin2 ..."
517 Provide an alternate qemu binary (or list of binaries). This can
518 be overridden at runtime by setting the "LIBGUESTFS_HV" environment
519 variable.
520 --with-supermin-packager-config=yum.conf
522 This passes the --packager-config option to supermin(1).
523 The most common use for this is to build the appliance using an
525 alternate repository (instead of using the installed
526 yum/dnf/apt/etc configuration to find and download packages). You
527 might need to use this if you want to build libguestfs without
528 having a network connection. Examples of using this can be found
529 in the Fedora "libguestfs.spec" file (see "BUILDING A PACKAGE FOR
530 FEDORA" below for resources).
531 --with-supermin-extra-options="--opt1 --opt2 ..."
533 Pass additional options to supermin(1). See appliance/make.sh.in
534 to understand precisely what this does.
535 PYTHON
537 This environment variable may be set to point to a python binary
538 (eg. "python3"). When "./configure" runs, it inspects this python
539 binary to find the version of Python, the location of Python
540 libraries and so on. See "BUILDING PYTHON 2 AND PYTHON 3 BINDINGS"
541 below.
542 SUPERMIN
544 This environment variable can be set to choose an alternative
545 supermin(1) binary. This might be used, for example, if you want
546 to use a newer upstream version of supermin than is packaged for
547 your distro, or if supermin is not packaged at all. On RHEL 7, you
548 must set "SUPERMIN=/usr/bin/supermin5" when compiling libguestfs.
549
551 A common problem is with broken or incompatible qemu releases.
552 Different versions of qemu have problems booting the appliance for
554 different reasons. This varies between versions of qemu, and Linux
555 distributions which add their own patches.
556 If you find a problem, you could try using your own qemu built from
558 source (qemu is very easy to build from source), with a "qemu wrapper".
559 See "QEMU WRAPPERS" in guestfs(3).
560 By default the configure script will look for qemu-kvm (KVM support).
562 KVM is much faster than using plain qemu.
563 You may also need to enable KVM support for non-root users, by
565 following these instructions:
566 http://www.linux-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non-privileged_user.3F
567 On some systems, this will work too:
569 chmod 0666 /dev/kvm
571 On some systems, the chmod will not survive a reboot, and you will need
573 to make edits to the udev configuration.
574
576 export CC=clang
577 ./configure
578 make
579
581 To understand what the libguestfs appliance means, see
582 guestfs-internals(1).
583 If you are using non-Linux, or a Linux distribution that does not have
585 supermin(1) support, or simply if you don't want to build your own
586 libguestfs appliance, then you can use one of the prebuilt binary
587 appliances that we supply:
588 http://libguestfs.org/download/binaries/appliance
589 Build libguestfs like this:
591 ./configure --disable-appliance --disable-daemon
593 make
594 Set $LIBGUESTFS_PATH to the path where you unpacked the appliance
596 tarball, eg:
597 export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
599 and run the libguestfs programs and virt tools in the normal way, eg.
601 using the ./run script (see above).
602
604 The ./configure script detects the currently installed version of
605 Python using whatever program is called "python" in the current $PATH.
606 Libguestfs will build Python 2 or Python 3 bindings as appropriate.
607 You can override this behaviour by specifying an alternate Python
609 binary, eg:
610 PYTHON=/usr/bin/python3 ./configure
612 To build parallel Python 2 and Python 3 bindings, you will need to
614 build libguestfs twice. The second time, you can disable all the other
615 bindings and tools and just build the Python bindings. See the Fedora
616 spec file (see below) for a complete example of how to do this.
617
619 The Fedora spec file is stored under:
620 http://pkgs.fedoraproject.org/cgit/rpms/libguestfs.git/
621 Libguestfs is built in Fedora using the ordinary Fedora build system
623 (Koji).
624
626 Red Hat Enterprise Linux (RHEL) builds of libguestfs are heavily
627 patched. There are broadly two types of patches we apply:
628 · We disable many features that we do not wish to support for RHEL
630 customers. For example, the "libguestfs live" feature is disabled.
631 · We backport upstream features.
633 The patches we apply to RHEL releases are available publically in the
635 upstream git repository, in a branch called "rhel-x.y"
636 For example, the RHEL 7.3 patches are available here:
638 https://github.com/libguestfs/libguestfs/commits/rhel-7.3
639 The sources and spec files for RHEL versions of libguestfs are
641 available on https://git.centos.org/project/rpms, and see also
642 https://wiki.centos.org/Sources.
643
645 guestfs(3), guestfs-examples(3), guestfs-hacking(1),
646 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
647 guestfs-testing(1), libguestfs-test-tool(1),
648 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
649
651 Richard W.M. Jones ("rjones at redhat dot com")
652
654 Copyright (C) 2009-2020 Red Hat Inc.
655
657 This library is free software; you can redistribute it and/or modify it
658 under the terms of the GNU Lesser General Public License as published
659 by the Free Software Foundation; either version 2 of the License, or
660 (at your option) any later version.
661 This library is distributed in the hope that it will be useful, but
663 WITHOUT ANY WARRANTY; without even the implied warranty of
664 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
665 Lesser General Public License for more details.
666 You should have received a copy of the GNU Lesser General Public
668 License along with this library; if not, write to the Free Software
669 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
670 02110-1301 USA
671
673 To get a list of bugs against libguestfs, use this link:
674 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
675 To report a new bug against libguestfs, use this link:
677 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
678 When reporting a bug, please supply:
680 · The version of libguestfs.
682 · Where you got libguestfs (eg. which Linux distro, compiled from
684 source, etc)
685 · Describe the bug accurately and give a way to reproduce it.
687 · Run libguestfs-test-tool(1) and paste the complete, unedited output
689 into the bug report.
690libguestfs-1.42.0 2020-03-09 guestfs-building(1)