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.
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.07
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       realpath
111           Required.
112
113       flex
114       bison
115           Required.
116
117       Perl-compatible Regular Expressions (PCRE2) library
118           Required.
119
120       xorriso, genisoimage or mkisofs
121           One of these is Required.
122
123       libxml2
124           Required.
125
126       ncurses
127           Required.
128
129       augeas ≥ 1.2.0
130           Required.
131
132       ocaml-augeas
133           Required.  These are the OCaml bindings for Augeas, found at:
134           http://people.redhat.com/~rjones/augeas/
135
136       xz  Required.
137
138       zstd
139           Required.
140
141       Jansson ≥ 2.7
142           Required.
143
144       po4a
145           Required if compiling from git.  Optional if compiling from
146           tarball.
147
148       hivex ≥ 1.2.7
149       ocaml-hivex
150           Required.  ocaml-hivex is the OCaml binding for hivex, which is
151           required when building the daemon.
152
153       libmagic
154           Required.  This is the library used by the file(1) command.
155
156       libvirt ≥ 0.10.2
157           Optional.  Always use the latest possible version of libvirt.
158
159       xmllint
160           Optional.  Used only for tests.
161
162       libconfig
163           Optional.  Used to parse libguestfs’s own config files, eg.
164           /etc/libguestfs-tools.conf.
165
166       libselinux
167           Optional.  Used by the libvirt backend to securely confine the
168           appliance (sVirt).
169
170       readline
171           Optional.  For nicer command line editing in guestfish(1).
172
173       acl Optional.  Library and programs for handling POSIX ACLs.
174
175       libcap
176           Optional.  Library and programs for handling Linux capabilities.
177
178       libldm
179           Optional.  Library and ldmtool(1) for handling Windows Dynamic
180           Disks.
181
182       sd-journal
183           Optional.  Library for accessing systemd journals.
184
185       gdisk
186           Optional.  GPT disk support.
187
188       netpbm
189           Optional.  Render icons from guests.
190
191       icoutils
192           Optional.  Render icons from Windows guests.
193
194       librpm
195           Optional.  To parse the list of applications from RPM-based guests.
196
197       Perl "Expect"
198           Optional.  Perl module used to test virt-rescue(1).
199
200       FUSE
201           Optional.  fusermount(1), libfuse and kernel module are all needed
202           if you want guestmount(1) and/or mount-local support.
203
204       static glibc
205           Optional.  Used only for testing.
206
207       qemu-nbd
208       nbdkit ≥ 1.12
209           Optional.  qemu-nbd is used for testing.
210
211       curl
212           Optional.  Used by virt-builder for downloads.
213
214       GNU Privacy Guard (GnuPG, gpg) v1 or v2
215           Optional.  Used by virt-builder for checking digital signatures.
216
217       liblzma
218           Optional.  If available, virt-builder will use this library for
219           fast, parallel uncompression of templates.
220
221       python-evtx
222           Optional.  Used by virt-log(1) to parse Windows Event Log files.
223
224       OCaml gettext
225           Optional.  For localizing OCaml virt tools.
226
227       ocaml-ounit ≥ 2.0.0
228           Optional.  For testing the common OCaml modules.
229
230       Perl "Module::Build" ≥ 0.19
231       Perl "Test::More"
232           Optional.  Used to build and test the Perl bindings.
233
234       Python ≥ 3.6
235           Optional.  Used to build the Python bindings.  Python 2 support was
236           removed in libguestfs 1.42.1.
237
238       Python "unittest"
239           Optional.  Used to run the Python testsuite.
240
241       Ruby
242       rake
243       rubygem-minitest
244       rubygem-rdoc
245           Optional.  Used to build the Ruby bindings.
246
247       Java ≥ 1.6
248           Optional.  Java, JNI and jpackage-utils are needed for building
249           Java bindings.
250
251       GHC Optional.  Used to build the Haskell bindings.
252
253       PHP
254       phpize
255           Optional.  Used to build the PHP bindings.
256
257       glib2
258       gobject-introspection
259       gjs Optional.  Used to build and test the GObject bindings.
260
261       vala
262           Optional.  Used to build the Vala bindings.
263
264       LUA Optional.  Used to build the LUA bindings.
265
266       Erlang ≥ 23
267       ei  Optional.  Used to build the Erlang bindings.  Note that Erlang ≤
268           22 will not work unless you use libguestfs ≤ 1.42.
269
270       golang ≥ 1.1.1
271           Optional.  Used to build the Go bindings.
272
273       valgrind
274           Optional.  For testing memory problems.
275
276       libvirt-python
277           Optional.  For testing Python libvirt/libguestfs interactions.
278
279       Perl "libintl"
280           Optional.
281
282       bash-completion
283           Optional.  For tab-completion of commands in bash.
284
285       libtsk
286           Optional.  Library for filesystem forensics analysis.
287
288       yara ≥ 4.0.0
289           Optional.  Tool for categorizing files based on their content.
290

BUILDING FROM GIT

292       You will need to install additional dependencies "autoconf",
293       "automake", "gettext", OCaml findlib and po4a when building from git.
294
295        git clone https://github.com/libguestfs/libguestfs
296        cd libguestfs
297        git submodule update --init
298        autoreconf -i
299        ./configure CFLAGS=-fPIC
300        make
301

BUILDING FROM TARBALLS

303       Tarballs are downloaded from http://download.libguestfs.org/.  Stable
304       tarballs are signed with the GnuPG key for "rich@annexia.org", see
305       https://pgp.mit.edu/pks/lookup?op=vindex&search=0x91738F73E1B768A0.
306       The fingerprint is "F777 4FB1 AD07 4A7E 8C87 67EA 9173 8F73 E1B7 68A0".
307
308       Download and unpack the tarball.
309
310        cd libguestfs-1.xx.yy
311        ./configure
312        make
313

RUNNING THE TESTS

315       DO NOT run the tests as root!  Libguestfs can be built and tested as
316       non-root.  Running the tests as root could even be dangerous, don't do
317       it.
318
319       To sanity check that the build worked, do:
320
321        make quickcheck
322
323       To run the basic tests, do:
324
325        make check
326
327       There are many more tests you can run.  See guestfs-hacking(1) for
328       details.
329

INSTALLING

331       DO NOT use "make install"!  You'll end up with conflicting versions of
332       libguestfs installed, and this causes constant headaches for users.
333       See the next section for how to use the ./run script instead.
334
335       Distro packagers can use:
336
337        make INSTALLDIRS=vendor DESTDIR=[temp-build-dir] install
338

THE ./run SCRIPT

340       You can run guestfish(1), guestmount(1) and the virt tools without
341       needing to install them by using the ./run script in the top directory.
342       This script works by setting several environment variables.
343
344       For example:
345
346        ./run guestfish [usual guestfish args ...]
347
348        ./run virt-inspector [usual virt-inspector args ...]
349
350       The ./run script adds every libguestfs binary to the $PATH, so the
351       above examples run guestfish and virt-inspector from the build
352       directory (not the globally installed guestfish if there is one).
353
354       You can use the script from any directory.  If you wanted to run your
355       own libguestfs-using program, then the following command will also
356       work:
357
358        /path/to/libguestfs/run ./my_program [...]
359
360       You can also run the C programs under valgrind like this:
361
362        ./run valgrind [valgrind opts...] virt-cat [virt-cat opts...]
363
364       or under gdb:
365
366        ./run gdb --args virt-cat [virt-cat opts...]
367
368       This also works with sudo (eg. if you need root access for libvirt or
369       to access a block device):
370
371        sudo ./run virt-cat -d LinuxGuest /etc/passwd
372
373       To set environment variables, you can either do:
374
375        LIBGUESTFS_HV=/my/qemu ./run guestfish
376
377       or:
378
379        ./run env LIBGUESTFS_HV=/my/qemu guestfish
380

local* FILES

382       Files in the top source directory that begin with the prefix local* are
383       ignored by git.  These files can contain local configuration or scripts
384       that you need to build libguestfs.
385
386       I have a file called localconfigure which is a simple wrapper around
387       configure containing local configure customizations that I need.  It
388       looks like this:
389
390        . localenv
391        ./configure.sh \
392            -C \
393            --enable-werror \
394            "$@"
395
396       So I can use this to build libguestfs:
397
398        ./localconfigure && make
399
400       If there is a file in the top build directory called localenv, then it
401       will be sourced by "make".  This file can contain any local environment
402       variables needed, eg. for skipping tests:
403
404        # Skip this test, it is broken.
405        export SKIP_TEST_BTRFS_FSCK=1
406
407       Note that localenv is included by the top Makefile (so it’s a Makefile
408       fragment).  But if it is also sourced by your localconfigure script
409       then it is used as a shell script.
410

SELECTED ./configure SETTINGS

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

NOTES ABOUT QEMU AND KVM

536       A common problem is with broken or incompatible qemu releases.
537
538       Different versions of qemu have problems booting the appliance for
539       different reasons.  This varies between versions of qemu, and Linux
540       distributions which add their own patches.
541
542       If you find a problem, you could try using your own qemu built from
543       source (qemu is very easy to build from source), with a "qemu wrapper".
544       See "QEMU WRAPPERS" in guestfs(3).
545
546       By default the configure script will look for qemu-kvm (KVM support).
547       KVM is much faster than using plain qemu.
548
549       You may also need to enable KVM support for non-root users, by
550       following these instructions:
551       http://www.linux-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non-privileged_user.3F
552
553       On some systems, this will work too:
554
555        chmod 0666 /dev/kvm
556
557       On some systems, the chmod will not survive a reboot, and you will need
558       to make edits to the udev configuration.
559

USING CLANG (LLVM) INSTEAD OF GCC

561        export CC=clang
562        ./configure
563        make
564

USING A PREBUILT BINARY APPLIANCE

566       To understand what the libguestfs appliance means, see
567       guestfs-internals(1).
568
569       If you are using non-Linux, or a Linux distribution that does not have
570       supermin(1) support, or simply if you don't want to build your own
571       libguestfs appliance, then you can use one of the prebuilt binary
572       appliances that we supply:
573       http://libguestfs.org/download/binaries/appliance
574
575       Build libguestfs like this:
576
577        ./configure --disable-appliance --disable-daemon
578        make
579
580       Set $LIBGUESTFS_PATH to the path where you unpacked the appliance
581       tarball, eg:
582
583        export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
584
585       and run the libguestfs programs and virt tools in the normal way, eg.
586       using the ./run script (see above).
587

BUILDING A PACKAGE FOR FEDORA

589       The Fedora spec file is stored under:
590       http://pkgs.fedoraproject.org/cgit/rpms/libguestfs.git/
591
592       Libguestfs is built in Fedora using the ordinary Fedora build system
593       (Koji).
594

BUILDING A PACKAGE FOR RED HAT ENTERPRISE LINUX

596       Red Hat Enterprise Linux (RHEL) builds of libguestfs are heavily
597       patched.  There are broadly two types of patches we apply:
598
599       •   We disable many features that we do not wish to support for RHEL
600           customers.  For example, the "libguestfs live" feature is disabled.
601
602       •   We backport upstream features.
603
604       The patches we apply to RHEL releases are available publically in the
605       upstream git repository, in a branch called "rhel-x.y"
606
607       For example, the RHEL 7.3 patches are available here:
608       https://github.com/libguestfs/libguestfs/commits/rhel-7.3
609
610       The sources and spec files for RHEL versions of libguestfs are
611       available on https://git.centos.org/project/rpms, and see also
612       https://wiki.centos.org/Sources.
613

SEE ALSO

615       guestfs(3), guestfs-examples(3), guestfs-hacking(1),
616       guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
617       guestfs-testing(1), libguestfs-test-tool(1),
618       libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
619

AUTHORS

621       Richard W.M. Jones ("rjones at redhat dot com")
622
624       Copyright (C) 2009-2023 Red Hat Inc.
625

LICENSE

627       This library is free software; you can redistribute it and/or modify it
628       under the terms of the GNU Lesser General Public License as published
629       by the Free Software Foundation; either version 2 of the License, or
630       (at your option) any later version.
631
632       This library is distributed in the hope that it will be useful, but
633       WITHOUT ANY WARRANTY; without even the implied warranty of
634       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
635       Lesser General Public License for more details.
636
637       You should have received a copy of the GNU Lesser General Public
638       License along with this library; if not, write to the Free Software
639       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
640       02110-1301 USA
641

BUGS

643       To get a list of bugs against libguestfs, use this link:
644       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
645
646       To report a new bug against libguestfs, use this link:
647       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
648
649       When reporting a bug, please supply:
650
651       •   The version of libguestfs.
652
653       •   Where you got libguestfs (eg. which Linux distro, compiled from
654           source, etc)
655
656       •   Describe the bug accurately and give a way to reproduce it.
657
658       •   Run libguestfs-test-tool(1) and paste the complete, unedited output
659           into the bug report.
660
661
662
663libguestfs-1.51.9                 2023-12-09               guestfs-building(1)
Impressum