1guestfs-building(1) Virtualization Support guestfs-building(1)
2
3
4
6 guestfs-building - How to build libguestfs from source
7
9 This manual page describes how to build libguestfs from source.
10
11 The main steps are:
12
13 · Install the requirements.
14
15 · Build, either from the git repository or from a tarball.
16
17 · Run the tests.
18
19 · 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
25 dnf builddep libguestfs
26 dnf install autoconf automake libtool gettext-devel
27
28 On systems still using yum(8), do:
29
30 yum-builddep libguestfs
31 yum install autoconf automake libtool gettext-devel
32
33 Short cut for Debian or Ubuntu users
34 Use APT to install all the requirements:
35
36 apt-get build-dep libguestfs
37 apt-get install autoconf automake libtool-bin gettext
38
39 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
44 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
49 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
54 make -C appliance clean-supermin-appliance
55
56 qemu ≥ 1.3.0
57 Required.
58
59 qemu-img ≥ 1.3.0
60 Required.
61
62 kernel ≥ 2.6.34
63 Required. The following features must be enabled: "virtio-pci",
64 "virtio-serial", "virtio-block", "virtio-net".
65
66 supermin ≥ 5.1.18
67 Required. For alternatives, see "USING A PREBUILT BINARY
68 APPLIANCE" below.
69
70 glibc
71 Required. We use the custom printf formatters extension of glibc
72 (see "DAEMON CUSTOM PRINTF FORMATTERS" in guestfs-hacking(1)).
73
74 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
78 The "rpcgen" tool is optional, except if you want to compile from
79 git and/or patch libguestfs with new APIs.
80
81 Gcc or Clang
82 Required. We use "__attribute__((cleanup))" which is a GCC
83 extension also supported by Clang.
84
85 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
90 Perl "Pod::Man"
91 Perl "Pod::Simple"
92 Required. Part of Perl core.
93
94 OCaml ≥ 4.01
95 OCaml findlib
96 Required.
97
98 autoconf
99 automake
100 gettext
101 Required if compiling from git. Optional if compiling from
102 tarball.
103
104 cpio
105 Required.
106
107 gperf
108 Required.
109
110 flex
111 bison
112 Required.
113
114 Perl-compatible Regular Expressions (PCRE) library
115 Required.
116
117 genisoimage
118 Required.
119
120 libxml2
121 Required.
122
123 ncurses
124 Required.
125
126 augeas ≥ 1.2.0
127 Required.
128
129 xz Required.
130
131 Jansson ≥ 2.7
132 Required.
133
134 po4a
135 Required if compiling from git. Optional if compiling from
136 tarball.
137
138 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
143 libmagic
144 Required. This is the library used by the file(1) command.
145
146 libvirt ≥ 0.10.2
147 Optional. Always use the latest possible version of libvirt.
148
149 xmllint
150 Optional. Used only for tests.
151
152 libconfig
153 Optional. Used to parse libguestfs’s own config files, eg.
154 /etc/libguestfs-tools.conf.
155
156 libselinux
157 Optional. Used by the libvirt backend to securely confine the
158 appliance (sVirt).
159
160 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
164 systemtap
165 Optional. For userspace probes.
166
167 readline
168 Optional. For nicer command line editing in guestfish(1).
169
170 acl Optional. Library and programs for handling POSIX ACLs.
171
172 libcap
173 Optional. Library and programs for handling Linux capabilities.
174
175 libldm
176 Optional. Library and ldmtool(1) for handling Windows Dynamic
177 Disks.
178
179 sd-journal
180 Optional. Library for accessing systemd journals.
181
182 gdisk
183 Optional. GPT disk support.
184
185 netpbm
186 Optional. Render icons from guests.
187
188 icoutils
189 Optional. Render icons from Windows guests.
190
191 Perl "Expect"
192 Optional. Perl module used to test virt-rescue(1).
193
194 FUSE
195 Optional. fusermount(1), libfuse and kernel module are all needed
196 if you want guestmount(1) and/or mount-local support.
197
198 static glibc
199 Optional. Used only for testing.
200
201 qemu-nbd
202 nbdkit ≥ 1.12
203 Optional. qemu-nbd is used for testing.
204
205 uml_mkcow
206 Optional. For the UML backend.
207
208 curl
209 Optional. Used by virt-builder for downloads.
210
211 GNU Privacy Guard (GnuPG, gpg) v1 or v2
212 Optional. Used by virt-builder for checking digital signatures.
213
214 liblzma
215 Optional. If available, virt-builder will use this library for
216 fast, parallel uncompression of templates.
217
218 python-evtx
219 Optional. Used by virt-log(1) to parse Windows Event Log files.
220
221 OCaml gettext
222 Optional. For localizing OCaml virt tools.
223
224 ocaml-ounit ≥ 2.0.0
225 Optional. For testing the common OCaml modules.
226
227 Perl "Module::Build" ≥ 0.19
228 Perl "Test::More"
229 Optional. Used to build and test the Perl bindings.
230
231 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
236 Python "unittest"
237 Optional. Used to run the Python testsuite.
238
239 Ruby
240 rake
241 rubygem-minitest
242 rubygem-rdoc
243 Optional. Used to build the Ruby bindings.
244
245 Java ≥ 1.6
246 Optional. Java, JNI and jpackage-utils are needed for building
247 Java bindings.
248
249 GHC Optional. Used to build the Haskell bindings.
250
251 PHP
252 phpize
253 Optional. Used to build the PHP bindings.
254
255 glib2
256 gobject-introspection
257 gjs Optional. Used to build and test the GObject bindings.
258
259 vala
260 Optional. Used to build the Vala bindings.
261
262 LUA Optional. Used to build the LUA bindings.
263
264 Erlang
265 erl_interface
266 Optional. Used to build the Erlang bindings.
267
268 golang ≥ 1.1.1
269 Optional. Used to build the Go bindings.
270
271 valgrind
272 Optional. For testing memory problems.
273
274 Perl "Sys::Virt"
275 Optional.
276
277 libvirt-python
278 Optional. For testing Python libvirt/libguestfs interactions.
279
280 Perl "Win::Hivex"
281 Optional. Used by the virt-win-reg(1) tool.
282
283 Perl "Pod::Usage"
284 Optional. Used by some Perl virt tools.
285
286 Perl "libintl"
287 Optional.
288
289 bash-completion
290 Optional. For tab-completion of commands in bash.
291
292 libtsk
293 Optional. Library for filesystem forensics analysis.
294
295 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
302 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
314 Download and unpack the tarball.
315
316 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
325 To sanity check that the build worked, do:
326
327 make quickcheck
328
329 To run the basic tests, do:
330
331 make check
332
333 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
341 Distro packagers can use:
342
343 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
350 For example:
351
352 ./run guestfish [usual guestfish args ...]
353
354 ./run virt-inspector [usual virt-inspector args ...]
355
356 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
360 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
364 /path/to/libguestfs/run ./my_program [...]
365
366 You can also run the C programs under valgrind like this:
367
368 ./run valgrind [valgrind opts...] virt-cat [virt-cat opts...]
369
370 or under gdb:
371
372 ./run gdb --args virt-cat [virt-cat opts...]
373
374 This also works with sudo (eg. if you need root access for libvirt or
375 to access a block device):
376
377 sudo ./run virt-cat -d LinuxGuest /etc/passwd
378
379 To set environment variables, you can either do:
380
381 LIBGUESTFS_HV=/my/qemu ./run guestfish
382
383 or:
384
385 ./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
392 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
396 . localenv
397 ./autogen.sh \
398 -C \
399 --enable-werror \
400 "$@"
401
402 So I can use this to build libguestfs:
403
404 ./localconfigure && make
405
406 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
410 # Use an alternate python binary.
411 export PYTHON=python3
412 # Skip this test, it is broken.
413 export SKIP_TEST_BTRFS_FSCK=1
414
415 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
422 ./configure --help
423
424 to list them all. This section covers some of the more important ones.
425
426 --disable-appliance --disable-daemon
427 See "USING A PREBUILT BINARY APPLIANCE" below.
428
429 --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
443 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
446 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
450 --disable-fuse
451 Disable FUSE support in the API and the guestmount(1) tool.
452
453 --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
458 --disable-static
459 Don’t build a static linked version of the libguestfs library.
460
461 --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
467 --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
472 --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
477 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
482 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
487 --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
492 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
497 Note that if your distro is completely new then it may still
498 require upstream modifications.
499
500 --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
509 For custom and/or local builds, this can be set to "local" to
510 indicate this is not a distro build.
511
512 --without-libvirt
513 Compile libguestfs without libvirt support, even if libvirt
514 development libraries are installed.
515
516 --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
521 --with-supermin-packager-config=yum.conf
522 This passes the --packager-config option to supermin(1).
523
524 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
532 --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
536 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
543 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
553 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
557 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
561 By default the configure script will look for qemu-kvm (KVM support).
562 KVM is much faster than using plain qemu.
563
564 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
568 On some systems, this will work too:
569
570 chmod 0666 /dev/kvm
571
572 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
584 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
590 Build libguestfs like this:
591
592 ./configure --disable-appliance --disable-daemon
593 make
594
595 Set $LIBGUESTFS_PATH to the path where you unpacked the appliance
596 tarball, eg:
597
598 export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
599
600 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
608 You can override this behaviour by specifying an alternate Python
609 binary, eg:
610
611 PYTHON=/usr/bin/python3 ./configure
612
613 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
622 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
629 · We disable many features that we do not wish to support for RHEL
630 customers. For example, the "libguestfs live" feature is disabled.
631
632 · We backport upstream features.
633
634 The patches we apply to RHEL releases are available publically in the
635 upstream git repository, in a branch called "rhel-x.y"
636
637 For example, the RHEL 7.3 patches are available here:
638 https://github.com/libguestfs/libguestfs/commits/rhel-7.3
639
640 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
662 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
667 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
676 To report a new bug against libguestfs, use this link:
677 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
678
679 When reporting a bug, please supply:
680
681 · The version of libguestfs.
682
683 · Where you got libguestfs (eg. which Linux distro, compiled from
684 source, etc)
685
686 · Describe the bug accurately and give a way to reproduce it.
687
688 · Run libguestfs-test-tool(1) and paste the complete, unedited output
689 into the bug report.
690
691
692
693libguestfs-1.42.0 2020-03-09 guestfs-building(1)