=head1 NAME

p2v-building - How to build virt-p2v from source

=head1 DESCRIPTION

This manual page describes how to build virt-p2v from source.

The main steps are:

=over 4

=item *

Install the requirements.

=item *

Build, either from the git repository or from a tarball.

=item *

Run the tests.

=item *

Run the tools from the source directory, or install.

=back

=head1 REQUIREMENTS

=head2 Full list of requirements

=over 4

=item qemu-img E<ge> 2.2.0

I<Required>.

=item Gcc or Clang

I<Required>.  We use C<__attribute__((cleanup))> which is a GCC
extension also supported by Clang.

=item Perl

I<Required>.  Various build steps and tests are written in Perl.  Perl
is not needed at runtime.

=item Perl C<Pod::Man>

=item Perl C<Pod::Simple>

I<Required>.  Part of Perl core.

=item autoconf

=item automake

I<Required> if compiling from git.
Optional if compiling from tarball.

=item Perl-compatible Regular Expressions (PCRE) library

I<Required>.

=item libxml2

I<Required>.

=item xz

I<Required>.

=item qemu-nbd

=item nbdkit

Optional.  qemu-nbd is used for testing.

L<virt-p2v(1)> requires either qemu-nbd or nbdkit, but these only need
to be present on the virt-p2v ISO, they do not need to be installed at
compile time.

=item Gtk E<ge> 2.24, or 3

I<Required>.

Either Gtk 2 or Gtk 3 can be used.  If you want to select a specific
version of Gtk, use S<C<./configure --with-gtk=2>> or
S<C<./configure --with-gtk=3>>.

=item D-Bus

Optional.

If the D-Bus low level C API is available, virt-p2v can send a D-Bus
message to logind to inhibit power saving (sleep, suspend, etc) during
P2V conversions.

If this API is not available at build time, then very long conversions
might be interrupted if the physical machine goes to sleep.

=item valgrind

Optional.  For testing memory problems.

=item bash-completion

Optional.  For tab-completion of commands in bash.

=back

=head1 BUILDING FROM GIT

You will need to install additional dependencies C<autoconf>,
and C<automake> when building from git.

 git clone https://github.com/libguestfs/virt-p2v
 cd virt-p2v
 ./autogen.sh
 make

=head1 BUILDING FROM TARBALLS

Tarballs are downloaded from L<http://download.libguestfs.org/>.
Stable tarballs are signed with the GnuPG key for C<rich@annexia.org>,
see
L<https://pgp.mit.edu/pks/lookup?op=vindex&search=0x91738F73E1B768A0>.
The fingerprint is C<F777 4FB1 AD07 4A7E 8C87 67EA 9173 8F73 E1B7 68A0>.

Download and unpack the tarball.

 cd virt-p2v-1.xx.yy
 ./configure
 make

=head1 RUNNING THE TESTS

B<DO NOT run the tests as root!>  Virt-p2v can be built and tested as
non-root.  Running the tests as root could even be dangerous, don't do
it.

To run the tests, do:

 make check

There are many more tests you can run.  See L<p2v-hacking(1)>
for details.

=head1 INSTALLING

B<DO NOT use C<make install>!>  You'll end up with conflicting versions
of virt-p2v installed, and this causes constant headaches for users.
See the next section for how to use the F<./run> script instead.

Distro packagers can use:

 make DESTDIR=[temp-build-dir] install

=head1 THE ./run SCRIPT

You can test L<virt-p2v(1)> and the other tools without needing
to install them by using the F<./run> script in the top directory.
This script works by setting several environment variables.

For example:

 ./run virt-p2v-make-disk [usual virt-p2v-make-disk args ...]

The F<./run> script adds every virt-p2v binary to the C<$PATH>, so
the above example run virt-p2v-make-disk from the build directory
(not the globally installed virt-p2v-make-disk if there is one).

=head1 SELECTED ./configure SETTINGS

There are many C<./configure> options.  Use:

 ./configure --help

to list them all.  This section covers some of the more important
ones.

=over 4

=item B<--disable-gnulib-tests>

On some platforms the GNUlib test suite can be flaky.  This disables
it, since errors in the GNUlib test suite are often not important.

=item B<--enable-werror>

This turns compiler warnings into errors (ie. C<-Werror>).  Use this
for development, especially when submitting patches.  It should
generally I<not> be used for production or distro builds.

=item B<--with-extra=">I<distroname>=I<version>,...B<">

=item B<--with-extra="local">

This option appends a text to the version of the virt-p2v tools.
It is a free text field, but a good idea is to encode a
comma-separated list of facts such as the distro name and version,
and anything else that may help with debugging problems raised
by users.

For custom and/or local builds, this can be set to C<local> to
indicate this is I<not> a distro build.

=item B<--with-gtk=3>

This option forces virt-p2v to be built against Gtk 3, which is
currently the most widely tested configuration.

=back

=head1 USING CLANG (LLVM) INSTEAD OF GCC

 export CC=clang
 ./configure
 make

=head1 BUILDING i686 32 BIT VIRT-P2V

I<(This section only applies on the x86-64 architecture.)>

Building a 32 bit virt-p2v (i686) binary improves compatibility with
older hardware.  See L<virt-p2v-make-disk(1)> for details.  Although
virt-p2v is a simple Gtk application, it is not especially easy to
build just virt-p2v as a 32 bit application on a 64 bit host.  Usually
the simplest way is to use a 32 bit chroot or even a 32 bit virtual
machine to build virt-p2v.

On Fedora you can use the L<mock(1)> tool.  For example:

 fedpkg mockbuild --root fedora-23-i386

This will result in a F<virt-v2v-*.i686.rpm> file which can be
unpacked to extract the 32 bit virt-p2v binary.

The binary may be compressed to either F<virt-p2v.i686.xz>, or
F<$libdir/virt-p2v/virt-p2v.i686.xz> or
F<$VIRT_P2V_DATA_DIR/virt-p2v.i686.xz> as appropriate.  This enables
the L<virt-p2v-make-disk(1)> I<--arch> option.

=head1 SEE ALSO

L<p2v-hacking(1)>,
L<p2v-release-notes(1)>,
L<http://libguestfs.org/>.

=head1 AUTHORS

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 COPYRIGHT

Copyright (C) 2009-2019 Red Hat Inc.
