1guestfs-building(1)         Virtualization Support         guestfs-building(1)
2
3
4

NAME

6       guestfs-building - How to build libguestfs from source
7

DESCRIPTION

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

REQUIREMENTS

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.  Virt-p2v and virt-v2v requires qemu-img ≥ 2.2.0.
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.0
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.0.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
203           Optional.  qemu-nbd is used for testing.
204
205           virt-p2v(1) requires either qemu-nbd or nbdkit, but these only need
206           to be present on the virt-p2v ISO, they do not need to be installed
207           at compile time.
208
209       uml_mkcow
210           Optional.  For the UML backend.
211
212       curl
213           Optional.  Used by virt-builder for downloads.
214
215       GNU Privacy Guard (GnuPG, gpg) v1 or v2
216           Optional.  Used by virt-builder for checking digital signatures.
217
218       liblzma
219           Optional.  If available, virt-builder will use this library for
220           fast, parallel uncompression of templates.
221
222       Gtk ≥ 2.24, or 3
223           Optional.
224
225           Used by the virt-p2v graphical user interface.
226
227           Either Gtk 2 or Gtk 3 can be used.  If you want to select a
228           specific version of Gtk, use "./configure --with-gtk=2" or
229           "./configure --with-gtk=3".
230
231       D-Bus
232           Optional.
233
234           If the D-Bus low level C API is available, virt-p2v can send a
235           D-Bus message to logind to inhibit power saving (sleep, suspend,
236           etc) during P2V conversions.
237
238           If this API is not available at build time, then very long
239           conversions might be interrupted if the physical machine goes to
240           sleep.
241
242       zip
243       unzip
244           Optional.  Used by virt-v2v to handle OVA files.
245
246       python-evtx
247           Optional.  Used by virt-log(1) to parse Windows Event Log files.
248
249       OCaml gettext
250           Optional.  For localizing OCaml virt tools.
251
252       ocaml-ounit ≥ 2.0.0
253           Optional.  For testing the common OCaml modules.
254
255       ocaml-libvirt ≥ 0.6.1.5
256           Optional.  For building the optional virt-v2v test harness.
257
258       Perl "Module::Build" ≥ 0.19
259       Perl "Test::More"
260           Optional.  Used to build and test the Perl bindings.
261
262       Python ≥ 2.2
263           Optional.  Used to build the Python bindings.  For building Python
264           2 or Python 3 bindings, see "BUILDING PYTHON 2 AND PYTHON 3
265           BINDINGS" below.
266
267       Python "unittest"
268           Optional.  Used to run the Python testsuite.
269
270       Ruby
271       rake
272       rubygem-minitest
273       rubygem-rdoc
274           Optional.  Used to build the Ruby bindings.
275
276       Java ≥ 1.6
277           Optional.  Java, JNI and jpackage-utils are needed for building
278           Java bindings.
279
280       GHC Optional.  Used to build the Haskell bindings.
281
282       PHP
283       phpize
284           Optional.  Used to build the PHP bindings.
285
286       glib2
287       gobject-introspection
288       gjs Optional.  Used to build and test the GObject bindings.
289
290       LUA Optional.  Used to build the LUA bindings.
291
292       Erlang
293       erl_interface
294           Optional.  Used to build the Erlang bindings.
295
296       golang ≥ 1.1.1
297           Optional.  Used to build the Go bindings.
298
299       valgrind
300           Optional.  For testing memory problems.
301
302       Perl "Sys::Virt"
303           Optional.
304
305       libvirt-python
306           Optional.  For testing Python libvirt/libguestfs interactions.
307
308       Perl "Win::Hivex"
309           Optional.  Used by the virt-win-reg(1) tool.
310
311       Perl "Pod::Usage"
312           Optional.  Used by some Perl virt tools.
313
314       Perl "libintl"
315           Optional.
316
317       bash-completion
318           Optional.  For tab-completion of commands in bash.
319
320       libtsk
321           Optional.  Library for filesystem forensics analysis.
322
323       yara
324           Optional.  Tool for categorizing files based on their content.
325

BUILDING FROM GIT

327       You will need to install additional dependencies "autoconf",
328       "automake", "gettext", OCaml findlib and po4a when building from git.
329
330        git clone https://github.com/libguestfs/libguestfs
331        cd libguestfs
332        ./autogen.sh
333        make
334

BUILDING FROM TARBALLS

336       Tarballs are downloaded from http://download.libguestfs.org/.  Stable
337       tarballs are signed with the GnuPG key for "rich@annexia.org", see
338       https://pgp.mit.edu/pks/lookup?op=vindex&search=0x91738F73E1B768A0.
339       The fingerprint is "F777 4FB1 AD07 4A7E 8C87 67EA 9173 8F73 E1B7 68A0".
340
341       Download and unpack the tarball.
342
343        cd libguestfs-1.xx.yy
344        ./configure
345        make
346

RUNNING THE TESTS

348       DO NOT run the tests as root!  Libguestfs can be built and tested as
349       non-root.  Running the tests as root could even be dangerous, don't do
350       it.
351
352       To sanity check that the build worked, do:
353
354        make quickcheck
355
356       To run the basic tests, do:
357
358        make check
359
360       There are many more tests you can run.  See guestfs-hacking(1) for
361       details.
362

INSTALLING

364       DO NOT use "make install"!  You'll end up with conflicting versions of
365       libguestfs installed, and this causes constant headaches for users.
366       See the next section for how to use the ./run script instead.
367
368       Distro packagers can use:
369
370        make INSTALLDIRS=vendor DESTDIR=[temp-build-dir] install
371

THE ./run SCRIPT

373       You can run guestfish(1), guestmount(1) and the virt tools without
374       needing to install them by using the ./run script in the top directory.
375       This script works by setting several environment variables.
376
377       For example:
378
379        ./run guestfish [usual guestfish args ...]
380
381        ./run virt-inspector [usual virt-inspector args ...]
382
383       The ./run script adds every libguestfs binary to the $PATH, so the
384       above examples run guestfish and virt-inspector from the build
385       directory (not the globally installed guestfish if there is one).
386
387       You can use the script from any directory.  If you wanted to run your
388       own libguestfs-using program, then the following command will also
389       work:
390
391        /path/to/libguestfs/run ./my_program [...]
392
393       You can also run the C programs under valgrind like this:
394
395        ./run valgrind [valgrind opts...] virt-cat [virt-cat opts...]
396
397       or under gdb:
398
399        ./run gdb --args virt-cat [virt-cat opts...]
400
401       This also works with sudo (eg. if you need root access for libvirt or
402       to access a block device):
403
404        sudo ./run virt-cat -d LinuxGuest /etc/passwd
405
406       To set environment variables, you can either do:
407
408        LIBGUESTFS_HV=/my/qemu ./run guestfish
409
410       or:
411
412        ./run env LIBGUESTFS_HV=/my/qemu guestfish
413

local* FILES

415       Files in the top source directory that begin with the prefix local* are
416       ignored by git.  These files can contain local configuration or scripts
417       that you need to build libguestfs.
418
419       I have a file called localconfigure which is a simple wrapper around
420       autogen.sh containing local configure customizations that I need.  It
421       looks like this:
422
423        . localenv
424        ./autogen.sh \
425            -C \
426            --enable-werror \
427            "$@"
428
429       So I can use this to build libguestfs:
430
431        ./localconfigure && make
432
433       If there is a file in the top build directory called localenv, then it
434       will be sourced by "make".  This file can contain any local environment
435       variables needed, eg. for skipping tests:
436
437        # Use an alternate python binary.
438        export PYTHON=python3
439        # Skip this test, it is broken.
440        export SKIP_TEST_BTRFS_FSCK=1
441
442       Note that localenv is included by the top Makefile (so it’s a Makefile
443       fragment).  But if it is also sourced by your localconfigure script
444       then it is used as a shell script.
445

SELECTED ./configure SETTINGS

447       There are many "./configure" options.  Use:
448
449        ./configure --help
450
451       to list them all.  This section covers some of the more important ones.
452
453       --disable-appliance --disable-daemon
454           See "USING A PREBUILT BINARY APPLIANCE" below.
455
456       --disable-erlang
457       --disable-gobject
458       --disable-golang
459       --disable-haskell
460       --disable-lua
461       --disable-ocaml
462       --disable-perl
463       --disable-php
464       --disable-python
465       --disable-ruby
466           Disable specific language bindings, even if "./configure" finds all
467           the necessary libraries are installed so that they could be
468           compiled.
469
470           Note that disabling OCaml (bindings) or Perl will have the knock-on
471           effect of disabling parts of the test suite and some tools.
472
473           OCaml is required to build libguestfs and this requirement cannot
474           be removed.  Using --disable-ocaml only disables the bindings and
475           OCaml tools.
476
477       --disable-fuse
478           Disable FUSE support in the API and the guestmount(1) tool.
479
480       --disable-gnulib-tests
481           On some platforms the GNUlib test suite can be flaky.  This
482           disables it, since errors in the GNUlib test suite are often not
483           important.
484
485       --disable-static
486           Don’t build a static linked version of the libguestfs library.
487
488       --enable-install-daemon
489           Normally guestfsd(8) is not installed by "make install", since that
490           wouldn't be useful (instead it is "installed" inside the supermin
491           appliance).  However if packagers are building "libguestfs live"
492           then they should use this option.
493
494       --enable-werror
495           This turns compiler warnings into errors (ie. "-Werror").  Use this
496           for development, especially when submitting patches.  It should
497           generally not be used for production or distro builds.
498
499       --with-default-backend=libvirt
500           This controls the default method that libguestfs uses to run qemu
501           (see "BACKEND" in guestfs(3)).  If not specified, the default
502           backend is "direct", which means libguestfs runs qemu directly.
503
504           Fedora and Red Hat Enterprise Linux (RHEL) ≥ 7 use this flag to
505           change the default backend to "libvirt", because (especially in
506           RHEL) the policy is not to allow any program to run qemu except via
507           libvirt.
508
509           Note that despite this setting, all backends are built into
510           libguestfs, and you can override the backend at runtime by setting
511           the $LIBGUESTFS_BACKEND environment variable (or using API
512           methods).
513
514       --with-distro=REDHAT|DEBIAN|...
515           Libguestfs needs to know which Linux distro is in use so it can
516           choose package names for the appliance correctly (see for example
517           appliance/packagelist.in).  It normally does this automatically.
518
519           However if you can building or packaging libguestfs on a new distro
520           then you can use --with-distro to specify that the distro is
521           similar to an existing one (eg. --with-distro=REDHAT if the distro
522           is a new Red Hat or CentOS derivative).
523
524           Note that if your distro is completely new then it may still
525           require upstream modifications.
526
527       --with-extra="distroname=version,libvirt,..."
528       --with-extra="local"
529           This option controls the "extra" field returned by
530           "guestfs_version" in guestfs(3) and also printed by virt tools'
531           --version option.  It is a free text field, but a good idea is to
532           encode a comma-separated list of facts such as the distro name and
533           version, whether libvirt is the default backend, and anything else
534           that may help with debugging problems raised by users.
535
536           For custom and/or local builds, this can be set to "local" to
537           indicate this is not a distro build.
538
539       --without-libvirt
540           Compile libguestfs without libvirt support, even if libvirt
541           development libraries are installed.
542
543       --with-gtk=2
544           This option forces virt-p2v to be built against Gtk 2, which is
545           currently the most widely tested configuration.
546
547       --with-qemu="bin1 bin2 ..."
548           Provide an alternate qemu binary (or list of binaries).  This can
549           be overridden at runtime by setting the "LIBGUESTFS_HV" environment
550           variable.
551
552       --with-supermin-packager-config=yum.conf
553           This passes the --packager-config option to supermin(1).
554
555           The most common use for this is to build the appliance using an
556           alternate repository (instead of using the installed
557           yum/dnf/apt/etc configuration to find and download packages).  You
558           might need to use this if you want to build libguestfs without
559           having a network connection.  Examples of using this can be found
560           in the Fedora "libguestfs.spec" file (see "BUILDING A PACKAGE FOR
561           FEDORA" below for resources).
562
563       --with-supermin-extra-options="--opt1 --opt2 ..."
564           Pass additional options to supermin(1).  See appliance/make.sh.in
565           to understand precisely what this does.
566
567       PYTHON
568           This environment variable may be set to point to a python binary
569           (eg. "python3").  When "./configure" runs, it inspects this python
570           binary to find the version of Python, the location of Python
571           libraries and so on.  See "BUILDING PYTHON 2 AND PYTHON 3 BINDINGS"
572           below.
573
574       SUPERMIN
575           This environment variable can be set to choose an alternative
576           supermin(1) binary.  This might be used, for example, if you want
577           to use a newer upstream version of supermin than is packaged for
578           your distro, or if supermin is not packaged at all.  On RHEL 7, you
579           must set "SUPERMIN=/usr/bin/supermin5" when compiling libguestfs.
580

NOTES ABOUT QEMU AND KVM

582       A common problem is with broken or incompatible qemu releases.
583
584       Different versions of qemu have problems booting the appliance for
585       different reasons.  This varies between versions of qemu, and Linux
586       distributions which add their own patches.
587
588       If you find a problem, you could try using your own qemu built from
589       source (qemu is very easy to build from source), with a "qemu wrapper".
590       See "QEMU WRAPPERS" in guestfs(3).
591
592       By default the configure script will look for qemu-kvm (KVM support).
593       KVM is much faster than using plain qemu.
594
595       You may also need to enable KVM support for non-root users, by
596       following these instructions:
597       http://www.linux-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non-privileged_user.3F
598
599       On some systems, this will work too:
600
601        chmod 0666 /dev/kvm
602
603       On some systems, the chmod will not survive a reboot, and you will need
604       to make edits to the udev configuration.
605

USING CLANG (LLVM) INSTEAD OF GCC

607        export CC=clang
608        ./configure
609        make
610

USING A PREBUILT BINARY APPLIANCE

612       To understand what the libguestfs appliance means, see
613       guestfs-internals(1).
614
615       If you are using non-Linux, or a Linux distribution that does not have
616       supermin(1) support, or simply if you don't want to build your own
617       libguestfs appliance, then you can use one of the prebuilt binary
618       appliances that we supply:
619       http://libguestfs.org/download/binaries/appliance
620
621       Build libguestfs like this:
622
623        ./configure --disable-appliance --disable-daemon
624        make
625
626       Set $LIBGUESTFS_PATH to the path where you unpacked the appliance
627       tarball, eg:
628
629        export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
630
631       and run the libguestfs programs and virt tools in the normal way, eg.
632       using the ./run script (see above).
633

BUILDING PYTHON 2 AND PYTHON 3 BINDINGS

635       The ./configure script detects the currently installed version of
636       Python using whatever program is called "python" in the current $PATH.
637       Libguestfs will build Python 2 or Python 3 bindings as appropriate.
638
639       You can override this behaviour by specifying an alternate Python
640       binary, eg:
641
642        PYTHON=/usr/bin/python3 ./configure
643
644       To build parallel Python 2 and Python 3 bindings, you will need to
645       build libguestfs twice.  The second time, you can disable all the other
646       bindings and tools and just build the Python bindings.  See the Fedora
647       spec file (see below) for a complete example of how to do this.
648

BUILDING A PACKAGE FOR FEDORA

650       The Fedora spec file is stored under:
651       http://pkgs.fedoraproject.org/cgit/rpms/libguestfs.git/
652
653       Libguestfs is built in Fedora using the ordinary Fedora build system
654       (Koji).
655

BUILDING A PACKAGE FOR RED HAT ENTERPRISE LINUX

657       Red Hat Enterprise Linux (RHEL) builds of libguestfs are heavily
658       patched.  There are broadly two types of patches we apply:
659
660       ·   We disable many features that we do not wish to support for RHEL
661           customers.  For example, the "libguestfs live" feature is disabled.
662
663       ·   We backport upstream features.
664
665       The patches we apply to RHEL releases are available publically in the
666       upstream git repository, in a branch called "rhel-x.y"
667
668       For example, the RHEL 7.3 patches are available here:
669       https://github.com/libguestfs/libguestfs/commits/rhel-7.3
670
671       The sources and spec files for RHEL versions of libguestfs are
672       available on https://git.centos.org/project/rpms, and see also
673       https://wiki.centos.org/Sources.
674

BUILDING i686 32 BIT VIRT-P2V

676       (This section only applies on the x86-64 architecture.)
677
678       Building a 32 bit virt-p2v (i686) binary improves compatibility with
679       older hardware.  See virt-p2v-make-disk(1) for details.  Although
680       virt-p2v is a simple Gtk application, it is not especially easy to
681       build just virt-p2v as a 32 bit application on a 64 bit host.  Usually
682       the simplest way is to use a 32 bit chroot or even a 32 bit virtual
683       machine to build libguestfs.
684
685       On Fedora you can use the mock(1) tool.  For example:
686
687        fedpkg mockbuild --root fedora-23-i386
688
689       This will result in a virt-v2v-*.i686.rpm file which can be unpacked to
690       extract the 32 bit virt-p2v binary.
691
692       The binary may be compressed to either p2v/virt-p2v.i686.xz, or
693       $libdir/virt-p2v/virt-p2v.i686.xz or
694       $VIRT_P2V_DATA_DIR/virt-p2v.i686.xz as appropriate.  This enables the
695       virt-p2v-make-disk(1) --arch option.
696

SEE ALSO

698       guestfs(3), guestfs-examples(3), guestfs-hacking(1),
699       guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
700       guestfs-testing(1), libguestfs-test-tool(1),
701       libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
702

AUTHORS

704       Richard W.M. Jones ("rjones at redhat dot com")
705
707       Copyright (C) 2009-2019 Red Hat Inc.
708

LICENSE

710       This library is free software; you can redistribute it and/or modify it
711       under the terms of the GNU Lesser General Public License as published
712       by the Free Software Foundation; either version 2 of the License, or
713       (at your option) any later version.
714
715       This library is distributed in the hope that it will be useful, but
716       WITHOUT ANY WARRANTY; without even the implied warranty of
717       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
718       Lesser General Public License for more details.
719
720       You should have received a copy of the GNU Lesser General Public
721       License along with this library; if not, write to the Free Software
722       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
723       02110-1301 USA
724

BUGS

726       To get a list of bugs against libguestfs, use this link:
727       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
728
729       To report a new bug against libguestfs, use this link:
730       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
731
732       When reporting a bug, please supply:
733
734       ·   The version of libguestfs.
735
736       ·   Where you got libguestfs (eg. which Linux distro, compiled from
737           source, etc)
738
739       ·   Describe the bug accurately and give a way to reproduce it.
740
741       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
742           into the bug report.
743
744
745
746libguestfs-1.40.1                 2019-01-17               guestfs-building(1)
Impressum