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 ≥ 3.6
232 Optional. Used to build the Python bindings. Python 2 support was
233 removed in libguestfs 1.42.1.
234 Python "unittest"
236 Optional. Used to run the Python testsuite.
237 Ruby
239 rake
240 rubygem-minitest
241 rubygem-rdoc
242 Optional. Used to build the Ruby bindings.
243 Java ≥ 1.6
245 Optional. Java, JNI and jpackage-utils are needed for building
246 Java bindings.
247 GHC Optional. Used to build the Haskell bindings.
249 PHP
251 phpize
252 Optional. Used to build the PHP bindings.
253 glib2
255 gobject-introspection
256 gjs Optional. Used to build and test the GObject bindings.
257 vala
259 Optional. Used to build the Vala bindings.
260 LUA Optional. Used to build the LUA bindings.
262 Erlang ≥ 23
264 ei Optional. Used to build the Erlang bindings. Note that Erlang ≤
265 22 will not work unless you use libguestfs ≤ 1.42.
266 golang ≥ 1.1.1
268 Optional. Used to build the Go bindings.
269 valgrind
271 Optional. For testing memory problems.
272 Perl "Sys::Virt"
274 Optional.
275 libvirt-python
277 Optional. For testing Python libvirt/libguestfs interactions.
278 Perl "Win::Hivex"
280 Optional. Used by the virt-win-reg(1) tool.
281 Perl "Pod::Usage"
283 Optional. Used by some Perl virt tools.
284 Perl "libintl"
286 Optional.
287 bash-completion
289 Optional. For tab-completion of commands in bash.
290 libtsk
292 Optional. Library for filesystem forensics analysis.
293 yara
295 Optional. Tool for categorizing files based on their content.
296
298 You will need to install additional dependencies "autoconf",
299 "automake", "gettext", OCaml findlib and po4a when building from git.
300 git clone https://github.com/libguestfs/libguestfs
302 cd libguestfs
303 git submodule update --init
304 CFLAGS=-fPIC ./autogen.sh
305 make
306
308 Tarballs are downloaded from http://download.libguestfs.org/. Stable
309 tarballs are signed with the GnuPG key for "rich@annexia.org", see
310 https://pgp.mit.edu/pks/lookup?op=vindex&search=0x91738F73E1B768A0.
311 The fingerprint is "F777 4FB1 AD07 4A7E 8C87 67EA 9173 8F73 E1B7 68A0".
312 Download and unpack the tarball.
314 cd libguestfs-1.xx.yy
316 ./configure
317 make
318
320 DO NOT run the tests as root! Libguestfs can be built and tested as
321 non-root. Running the tests as root could even be dangerous, don't do
322 it.
323 To sanity check that the build worked, do:
325 make quickcheck
327 To run the basic tests, do:
329 make check
331 There are many more tests you can run. See guestfs-hacking(1) for
333 details.
334
336 DO NOT use "make install"! You'll end up with conflicting versions of
337 libguestfs installed, and this causes constant headaches for users.
338 See the next section for how to use the ./run script instead.
339 Distro packagers can use:
341 make INSTALLDIRS=vendor DESTDIR=[temp-build-dir] install
343
345 You can run guestfish(1), guestmount(1) and the virt tools without
346 needing to install them by using the ./run script in the top directory.
347 This script works by setting several environment variables.
348 For example:
350 ./run guestfish [usual guestfish args ...]
352 ./run virt-inspector [usual virt-inspector args ...]
354 The ./run script adds every libguestfs binary to the $PATH, so the
356 above examples run guestfish and virt-inspector from the build
357 directory (not the globally installed guestfish if there is one).
358 You can use the script from any directory. If you wanted to run your
360 own libguestfs-using program, then the following command will also
361 work:
362 /path/to/libguestfs/run ./my_program [...]
364 You can also run the C programs under valgrind like this:
366 ./run valgrind [valgrind opts...] virt-cat [virt-cat opts...]
368 or under gdb:
370 ./run gdb --args virt-cat [virt-cat opts...]
372 This also works with sudo (eg. if you need root access for libvirt or
374 to access a block device):
375 sudo ./run virt-cat -d LinuxGuest /etc/passwd
377 To set environment variables, you can either do:
379 LIBGUESTFS_HV=/my/qemu ./run guestfish
381 or:
383 ./run env LIBGUESTFS_HV=/my/qemu guestfish
385
387 Files in the top source directory that begin with the prefix local* are
388 ignored by git. These files can contain local configuration or scripts
389 that you need to build libguestfs.
390 I have a file called localconfigure which is a simple wrapper around
392 autogen.sh containing local configure customizations that I need. It
393 looks like this:
394 . localenv
396 ./autogen.sh \
397 -C \
398 --enable-werror \
399 "$@"
400 So I can use this to build libguestfs:
402 ./localconfigure && make
404 If there is a file in the top build directory called localenv, then it
406 will be sourced by "make". This file can contain any local environment
407 variables needed, eg. for skipping tests:
408 # Skip this test, it is broken.
410 export SKIP_TEST_BTRFS_FSCK=1
411 Note that localenv is included by the top Makefile (so it’s a Makefile
413 fragment). But if it is also sourced by your localconfigure script
414 then it is used as a shell script.
415
417 There are many "./configure" options. Use:
418 ./configure --help
420 to list them all. This section covers some of the more important ones.
422 --disable-appliance --disable-daemon
424 See "USING A PREBUILT BINARY APPLIANCE" below.
425 --disable-erlang
427 --disable-gobject
428 --disable-golang
429 --disable-haskell
430 --disable-lua
431 --disable-ocaml
432 --disable-perl
433 --disable-php
434 --disable-python
435 --disable-ruby
436 Disable specific language bindings, even if "./configure" finds all
437 the necessary libraries are installed so that they could be
438 compiled.
439 Note that disabling OCaml (bindings) or Perl will have the knock-on
441 effect of disabling parts of the test suite and some tools.
442 OCaml is required to build libguestfs and this requirement cannot
444 be removed. Using --disable-ocaml only disables the bindings and
445 OCaml tools.
446 --disable-fuse
448 Disable FUSE support in the API and the guestmount(1) tool.
449 --disable-gnulib-tests
451 On some platforms the GNUlib test suite can be flaky. This
452 disables it, since errors in the GNUlib test suite are often not
453 important.
454 --disable-static
456 Don’t build a static linked version of the libguestfs library.
457 --enable-install-daemon
459 Normally guestfsd(8) is not installed by "make install", since that
460 wouldn't be useful (instead it is "installed" inside the supermin
461 appliance). However if packagers are building "libguestfs live"
462 then they should use this option.
463 --enable-werror
465 This turns compiler warnings into errors (ie. "-Werror"). Use this
466 for development, especially when submitting patches. It should
467 generally not be used for production or distro builds.
468 --with-default-backend=libvirt
470 This controls the default method that libguestfs uses to run qemu
471 (see "BACKEND" in guestfs(3)). If not specified, the default
472 backend is "direct", which means libguestfs runs qemu directly.
473 Fedora and Red Hat Enterprise Linux (RHEL) ≥ 7 use this flag to
475 change the default backend to "libvirt", because (especially in
476 RHEL) the policy is not to allow any program to run qemu except via
477 libvirt.
478 Note that despite this setting, all backends are built into
480 libguestfs, and you can override the backend at runtime by setting
481 the $LIBGUESTFS_BACKEND environment variable (or using API
482 methods).
483 --with-distro=REDHAT|DEBIAN|...
485 Libguestfs needs to know which Linux distro is in use so it can
486 choose package names for the appliance correctly (see for example
487 appliance/packagelist.in). It normally does this automatically.
488 However if you can building or packaging libguestfs on a new distro
490 then you can use --with-distro to specify that the distro is
491 similar to an existing one (eg. --with-distro=REDHAT if the distro
492 is a new Red Hat or CentOS derivative).
493 Note that if your distro is completely new then it may still
495 require upstream modifications.
496 --with-extra="distroname=version,libvirt,..."
498 --with-extra="local"
499 This option controls the "extra" field returned by
500 "guestfs_version" in guestfs(3) and also printed by virt tools'
501 --version option. It is a free text field, but a good idea is to
502 encode a comma-separated list of facts such as the distro name and
503 version, whether libvirt is the default backend, and anything else
504 that may help with debugging problems raised by users.
505 For custom and/or local builds, this can be set to "local" to
507 indicate this is not a distro build.
508 --without-libvirt
510 Compile libguestfs without libvirt support, even if libvirt
511 development libraries are installed.
512 --with-qemu="bin1 bin2 ..."
514 Provide an alternate qemu binary (or list of binaries). This can
515 be overridden at runtime by setting the "LIBGUESTFS_HV" environment
516 variable.
517 --with-supermin-packager-config=yum.conf
519 This passes the --packager-config option to supermin(1).
520 The most common use for this is to build the appliance using an
522 alternate repository (instead of using the installed
523 yum/dnf/apt/etc configuration to find and download packages). You
524 might need to use this if you want to build libguestfs without
525 having a network connection. Examples of using this can be found
526 in the Fedora "libguestfs.spec" file (see "BUILDING A PACKAGE FOR
527 FEDORA" below for resources).
528 --with-supermin-extra-options="--opt1 --opt2 ..."
530 Pass additional options to supermin(1). See appliance/make.sh.in
531 to understand precisely what this does.
532 PYTHON
534 This environment variable may be set to point to a python binary
535 (eg. "python3"). When "./configure" runs, it inspects this python
536 binary to find the version of Python, the location of Python
537 libraries and so on.
538 SUPERMIN
540 This environment variable can be set to choose an alternative
541 supermin(1) binary. This might be used, for example, if you want
542 to use a newer upstream version of supermin than is packaged for
543 your distro, or if supermin is not packaged at all. On RHEL 7, you
544 must set "SUPERMIN=/usr/bin/supermin5" when compiling libguestfs.
545
547 A common problem is with broken or incompatible qemu releases.
548 Different versions of qemu have problems booting the appliance for
550 different reasons. This varies between versions of qemu, and Linux
551 distributions which add their own patches.
552 If you find a problem, you could try using your own qemu built from
554 source (qemu is very easy to build from source), with a "qemu wrapper".
555 See "QEMU WRAPPERS" in guestfs(3).
556 By default the configure script will look for qemu-kvm (KVM support).
558 KVM is much faster than using plain qemu.
559 You may also need to enable KVM support for non-root users, by
561 following these instructions:
562 http://www.linux-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non-privileged_user.3F
563 On some systems, this will work too:
565 chmod 0666 /dev/kvm
567 On some systems, the chmod will not survive a reboot, and you will need
569 to make edits to the udev configuration.
570
572 export CC=clang
573 ./configure
574 make
575
577 To understand what the libguestfs appliance means, see
578 guestfs-internals(1).
579 If you are using non-Linux, or a Linux distribution that does not have
581 supermin(1) support, or simply if you don't want to build your own
582 libguestfs appliance, then you can use one of the prebuilt binary
583 appliances that we supply:
584 http://libguestfs.org/download/binaries/appliance
585 Build libguestfs like this:
587 ./configure --disable-appliance --disable-daemon
589 make
590 Set $LIBGUESTFS_PATH to the path where you unpacked the appliance
592 tarball, eg:
593 export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
595 and run the libguestfs programs and virt tools in the normal way, eg.
597 using the ./run script (see above).
598
600 The Fedora spec file is stored under:
601 http://pkgs.fedoraproject.org/cgit/rpms/libguestfs.git/
602 Libguestfs is built in Fedora using the ordinary Fedora build system
604 (Koji).
605
607 Red Hat Enterprise Linux (RHEL) builds of libguestfs are heavily
608 patched. There are broadly two types of patches we apply:
609 · We disable many features that we do not wish to support for RHEL
611 customers. For example, the "libguestfs live" feature is disabled.
612 · We backport upstream features.
614 The patches we apply to RHEL releases are available publically in the
616 upstream git repository, in a branch called "rhel-x.y"
617 For example, the RHEL 7.3 patches are available here:
619 https://github.com/libguestfs/libguestfs/commits/rhel-7.3
620 The sources and spec files for RHEL versions of libguestfs are
622 available on https://git.centos.org/project/rpms, and see also
623 https://wiki.centos.org/Sources.
624
626 guestfs(3), guestfs-examples(3), guestfs-hacking(1),
627 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
628 guestfs-testing(1), libguestfs-test-tool(1),
629 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
630
632 Richard W.M. Jones ("rjones at redhat dot com")
633
635 Copyright (C) 2009-2020 Red Hat Inc.
636
638 This library is free software; you can redistribute it and/or modify it
639 under the terms of the GNU Lesser General Public License as published
640 by the Free Software Foundation; either version 2 of the License, or
641 (at your option) any later version.
642 This library is distributed in the hope that it will be useful, but
644 WITHOUT ANY WARRANTY; without even the implied warranty of
645 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
646 Lesser General Public License for more details.
647 You should have received a copy of the GNU Lesser General Public
649 License along with this library; if not, write to the Free Software
650 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
651 02110-1301 USA
652
654 To get a list of bugs against libguestfs, use this link:
655 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
656 To report a new bug against libguestfs, use this link:
658 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
659 When reporting a bug, please supply:
661 · The version of libguestfs.
663 · Where you got libguestfs (eg. which Linux distro, compiled from
665 source, etc)
666 · Describe the bug accurately and give a way to reproduce it.
668 · Run libguestfs-test-tool(1) and paste the complete, unedited output
670 into the bug report.
671libguestfs-1.44.0 2021-01-05 guestfs-building(1)