.\" Automatically generated by Podwrapper::Man 1.42.3 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "p2v-hacking 1"
.TH p2v-hacking 1 "2022-10-13" "virt-p2v-1.42.3" "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
p2v\-hacking \- extending and contributing to virt\-p2v
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This manual page is for hackers who want to extend virt\-p2v itself.
.PP
Virt\-p2v is a front end on virt\-v2v.  ie. All it does is act as a \s-1GUI\s0
front end, and it calls out to virt\-v2v to perform the actual
conversion.  Therefore most of the C code
is Gtk (\s-1GUI\s0) code, or supporting code for talking to the remote
conversion server.  There is no special support for physical machines
in virt\-v2v.  They are converted in the same way as foreign VMs.
.SH "THE SOURCE CODE"
.IX Header "THE SOURCE CODE"
Virt\-p2v source is located in the github repository
https://github.com/libguestfs/virt\-p2v
.PP
Virt\-p2v uses an autotools-based build system, with the main files
being \fIconfigure.ac\fR and \fIMakefile.am\fR.  See \*(L"\s-1THE BUILD SYSTEM\*(R"\s0.
.PP
To build from source, first read the \fBp2v\-building\fR\|(1).
.SS "\s-1SOURCE CODE SUBDIRECTORIES\s0"
.IX Subsection "SOURCE CODE SUBDIRECTORIES"
The majority of the source code is directly in the top level directory
of the sources.  There are also some subdirectories that contain some
specific sub-parts of virt\-p2v.
.IP "\fIbash\fR" 4
.IX Item "bash"
Bash tab-completion scripts.
.IP "\fIbuild-aux\fR" 4
.IX Item "build-aux"
Various build scripts used by autotools.
.IP "\fIminiexpect\fR" 4
.IX Item "miniexpect"
A copy of the miniexpect library from
http://git.annexia.org/?p=miniexpect.git;a=summary.
.IP "\fIcontrib\fR" 4
.IX Item "contrib"
Outside contributions, experimental parts.
.IP "\fIdocs\fR" 4
.IX Item "docs"
Miscellaneous manual pages.
.IP "\fIlibguestfs\fR" 4
.IX Item "libguestfs"
Some sources (mostly with utilities) copied from libguestfs.  Changes
to the sources there ought to be forwarded to libguestfs as well.
.IP "\fIm4\fR" 4
.IX Item "m4"
M4 macros used by autoconf.  See \*(L"\s-1THE BUILD SYSTEM\*(R"\s0.
.IP "\fIwebsite\fR" 4
.IX Item "website"
The virt\-p2v files of the http://libguestfs.org website.
.SS "\s-1THE BUILD SYSTEM\s0"
.IX Subsection "THE BUILD SYSTEM"
Virt\-p2v uses the \s-1GNU\s0 autotools build system (autoconf, automake).
.PP
The \fI./configure\fR script is generated from \fIconfigure.ac\fR and
\&\fIm4/p2v\-*.m4\fR.  Most of the configure script is split over many
m4 macro files by topic, for example \fIm4/p2v\-libraries.m4\fR deals
with the libraries required by virt\-p2v.
.PP
\&\fIsubdir\-rules.mk\fR is included in every \fIMakefile.am\fR (top level and
subdirectories).
.SS "\s-1UNDERSTANDING THE CODE\s0"
.IX Subsection "UNDERSTANDING THE CODE"
\&\fISee also:\fR \*(L"\s-1HOW VIRT\-P2V WORKS\*(R"\s0 in \fBvirt\-p2v\fR\|(1)
.PP
There are two paths through the code, \s-1GUI\s0 or non-GUI (parsing the
kernel command line):
.PP
.Vb 4
\& main.c ──────┬─────▶ gui.c ──────┬─────▶ conversion.c
\&              │                   │
\&              │                   │
\&              └────▶ kernel.c ────┘
.Ve
.PP
but both paths call back to the \fIconversion.c\fR function
\&\f(CW\*(C`start_conversion\*(C'\fR to run the remote virt\-v2v.
.PP
The main task of \fIgui.c\fR/\fIkernel.c\fR is to populate the virt\-v2v
configuration (\fIconfig.c\fR).
.PP
During conversion, we need to establish ssh connections, and that is
done using two libraries:
.PP
.Vb 1
\& conversion.c ──────▶ ssh.c ──────▶ miniexpect.c
.Ve
.PP
where \fIssh.c\fR is responsible for managing ssh connections overall,
and \fIminiexpect.c\fR implements \*(L"expect-like\*(R" functionality for talking
interactively to the remote virt\-v2v conversion server.
.PP
(Note that miniexpect is a separate library with its own upstream, so
if you patch miniexpect.c, then please make sure the changes get
reflected in miniexpect’s upstream too:
\&\fIhttp://git.annexia.org/?p=miniexpect.git;a=summary\fR)
.SH "RUNNING VIRT\-P2V"
.IX Header "RUNNING VIRT-P2V"
You can run the \fIvirt\-p2v\fR binary directly, but it will try to
convert your machine’s real \fI/dev/sda\fR which is unlikely to work
well.  However virt\-p2v also has a test mode in which you can supply a
test disk:
.PP
.Vb 1
\& make run\-virt\-p2v\-directly
.Ve
.PP
This is a wrapper around the \fBvirt\-p2v\fR\|(1) \fI\-\-test\-disk\fR option.
You can control the \*(L"physical machine\*(R" disk by setting
\&\f(CW\*(C`PHYSICAL_MACHINE\*(C'\fR to point to a disk image.
.PP
A more realistic test is to run virt\-p2v inside a \s-1VM\s0 on the local
machine.  To do that, do:
.PP
.Vb 2
\& make run\-virt\-p2v\-in\-a\-vm
\& make run\-virt\-p2v\-in\-an\-nvme\-vm
.Ve
.PP
These also run qemu with the \*(L"physical machine\*(R" disk (which you can
set by setting \f(CW\*(C`PHYSICAL_MACHINE\*(C'\fR), a virtual \s-1CD,\s0 and a variety of
network cards for testing.  The second target exposes the \*(L"physical
machine\*(R" disk as an NVMe controller, plus adds two blank disks as
distinct namespaces of another NVMe controller.  You can change the
qemu binary and add extra qemu options by setting \f(CW\*(C`QEMU\*(C'\fR and/or
\&\f(CW\*(C`QEMU_OPTIONS\*(C'\fR on the make commandline.
.PP
A third way to run virt\-p2v simulates fairly accurately the program
being downloaded over \s-1PXE\s0 and then doing an automatic conversion of
the source physical machine (the non-GUI path \*(-- see next section
below):
.PP
.Vb 1
\& make run\-virt\-p2v\-non\-gui\-conversion
.Ve
.SH "EXTENDING VIRT\-P2V"
.IX Header "EXTENDING VIRT-P2V"
.SS "\s-1FORMATTING CODE\s0"
.IX Subsection "FORMATTING CODE"
Our C source code generally adheres to some basic code-formatting
conventions.  The existing code base is not totally consistent on this
front, but we do prefer that contributed code be formatted similarly.
In short, use spaces-not-TABs for indentation, use 2 spaces for each
indentation level, and other than that, follow the K&R style.
.PP
If you use Emacs, add the following to one of your start-up files
(e.g., ~/.emacs), to help ensure that you get indentation right:
.PP
.Vb 9
\& ;;; In virt\-p2v, indent with spaces everywhere (not TABs).
\& ;;; Exceptions: Makefile and ChangeLog modes.
\& (add\-hook \*(Aqfind\-file\-hook
\&     \*(Aq(lambda () (if (and buffer\-file\-name
\&                          (string\-match "/virt\-p2v\e\e>"
\&                              (buffer\-file\-name))
\&                          (not (string\-equal mode\-name "Change Log"))
\&                          (not (string\-equal mode\-name "Makefile")))
\&                     (setq indent\-tabs\-mode nil))))
\& 
\& ;;; When editing C sources in virt\-p2v, use this style.
\& (defun virt\-p2v\-c\-mode ()
\&   "C mode with adjusted defaults for use with virt\-p2v."
\&   (interactive)
\&   (c\-set\-style "K&R")
\&   (setq c\-indent\-level 2)
\&   (setq c\-basic\-offset 2))
\& (add\-hook \*(Aqc\-mode\-hook
\&           \*(Aq(lambda () (if (string\-match "/virt\-p2v\e\e>"
\&                               (buffer\-file\-name))
\&                           (virt\-p2v\-c\-mode))))
.Ve
.SS "\s-1TESTING YOUR CHANGES\s0"
.IX Subsection "TESTING YOUR CHANGES"
Turn warnings into errors when developing to make warnings hard to
ignore:
.PP
.Vb 1
\& ./configure \-\-enable\-werror
.Ve
.PP
Useful targets are:
.ie n .IP """make check""" 4
.el .IP "\f(CWmake check\fR" 4
.IX Item "make check"
Runs the regular test suite.
.Sp
This is implemented using the regular automake \f(CW\*(C`TESTS\*(C'\fR target.  See
the automake documentation for details.
.ie n .IP """make check\-valgrind""" 4
.el .IP "\f(CWmake check\-valgrind\fR" 4
.IX Item "make check-valgrind"
Runs a subset of the test suite under valgrind.
.ie n .IP """make check\-slow""" 4
.el .IP "\f(CWmake check\-slow\fR" 4
.IX Item "make check-slow"
Runs some slow/long\-running tests which are not run by default.
.Sp
To mark a test as slow/long\-running:
.RS 4
.IP "\(bu" 4
Add it to the list of \f(CW\*(C`TESTS\*(C'\fR in the \fIMakefile.am\fR, just like a
normal test.
.IP "\(bu" 4
Modify the test so it checks if the \f(CW\*(C`SLOW=1\*(C'\fR environment variable is
set, and if \fInot\fR set it skips (ie. returns with exit code 77).  If
using \f(CW$TEST_FUNCTIONS\fR, you can call the function \f(CW\*(C`slow_test\*(C'\fR for
this.
.IP "\(bu" 4
Add a variable \f(CW\*(C`SLOW_TESTS\*(C'\fR to the \fIMakefile.am\fR listing the slow
tests.
.IP "\(bu" 4
Add a rule to the \fIMakefile.am\fR:
.Sp
.Vb 2
\& check\-slow:
\&   $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1
.Ve
.RE
.RS 4
.RE
.SS "\s-1VALGRIND\s0"
.IX Subsection "VALGRIND"
When you do \f(CW\*(C`make check\-valgrind\*(C'\fR, it searches for any \fIMakefile.am\fR
in the tree that has a \f(CW\*(C`check\-valgrind:\*(C'\fR target and runs it.
.PP
Writing the \fIMakefile.am\fR and tests correctly to use valgrind and
working with automake parallel tests is subtle.
.PP
If your tests are run via a shell script wrapper, then in the wrapper
use:
.PP
.Vb 1
\& $VG virt\-foo
.Ve
.PP
and in the \fIMakefile.am\fR use:
.PP
.Vb 2
\& check\-valgrind:
\&     make VG="@VG@" check
.Ve
.PP
However, if your binaries run directly from the \f(CW\*(C`TESTS\*(C'\fR rule, you
have to modify the \fIMakefile.am\fR like this:
.PP
.Vb 1
\& LOG_COMPILER = $(VG)
\& 
\& check\-valgrind:
\&     make VG="@VG@" check
.Ve
.PP
In either case, check that the right program is being tested by
examining the \fIvalgrind*\fR log files carefully.
.SS "\s-1SUBMITTING PATCHES\s0"
.IX Subsection "SUBMITTING PATCHES"
Submit patches to the mailing list:
http://www.redhat.com/mailman/listinfo/libguestfs
and \s-1CC\s0 to rjones@redhat.com.
.PP
You do not need to subscribe to the mailing list if you don’t want to.
There may be a short delay while your message is moderated.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBp2v\-building\fR\|(1),
\&\fBp2v\-release\-notes\fR\|(1),
http://libguestfs.org/.
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2009\-2019 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify it
under the terms of the \s-1GNU\s0 Lesser General Public License as published
by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This library is distributed in the hope that it will be useful, but
\&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the \s-1GNU\s0
Lesser General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 Lesser General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
.SH "BUGS"
.IX Header "BUGS"
To get a list of bugs against libguestfs (which include virt\-p2v),
use this link:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
.PP
To report a new bug against libguestfs, use this link:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
When reporting a bug, please supply:
.IP "\(bu" 4
The version of virt\-p2v.
.IP "\(bu" 4
Where you got virt\-p2v (eg. which Linux distro, compiled from source, etc)
.IP "\(bu" 4
Describe the bug accurately and give a way to reproduce it.