| p2v-hacking(1) | Virtualization Support | p2v-hacking(1) |
p2v-hacking - extending and contributing to virt-p2v
This manual page is for hackers who want to extend virt-p2v itself.
Virt-p2v is a front end on virt-v2v. ie. All it does is act as a GUI front end, and it calls out to virt-v2v to perform the actual conversion. Therefore most of the C code is Gtk (GUI) 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.
Virt-p2v source is located in the github repository https://github.com/libguestfs/virt-p2v
Virt-p2v uses an autotools-based build system, with the main files being configure.ac and Makefile.am. See "THE BUILD SYSTEM".
To build from source, first read the p2v-building(1).
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.
Virt-p2v uses the GNU autotools build system (autoconf, automake).
The ./configure script is generated from configure.ac and m4/p2v-*.m4. Most of the configure script is split over many m4 macro files by topic, for example m4/p2v-libraries.m4 deals with the libraries required by virt-p2v.
subdir-rules.mk is included in every Makefile.am (top level and subdirectories).
See also: "HOW VIRT-P2V WORKS" in virt-p2v(1)
There are two paths through the code, GUI or non-GUI (parsing the kernel command line):
main.c ──────┬─────▶ gui.c ──────┬─────▶ conversion.c
│ │
│ │
└────▶ kernel.c ────┘
but both paths call back to the conversion.c function "start_conversion" to run the remote virt-v2v.
The main task of gui.c/kernel.c is to populate the virt-v2v configuration (config.c).
During conversion, we need to establish ssh connections, and that is done using two libraries:
conversion.c ──────▶ ssh.c ──────▶ miniexpect.c
where ssh.c is responsible for managing ssh connections overall, and miniexpect.c implements "expect-like" functionality for talking interactively to the remote virt-v2v conversion server.
(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: http://git.annexia.org/?p=miniexpect.git;a=summary)
You can run the virt-p2v binary directly, but it will try to convert your machine’s real /dev/sda which is unlikely to work well. However virt-p2v also has a test mode in which you can supply a test disk:
make run-virt-p2v-directly
This is a wrapper around the virt-p2v(1) --test-disk option. You can control the "physical machine" disk by setting "PHYSICAL_MACHINE" to point to a disk image.
A more realistic test is to run virt-p2v inside a VM on the local machine. To do that, do:
make run-virt-p2v-in-a-vm
This also runs qemu with the "physical machine" disk (which you can set by setting "PHYSICAL_MACHINE"), a virtual CD, and a variety of network cards for testing. You can change the qemu binary and add extra qemu options by setting "QEMU" and/or "QEMU_OPTIONS" on the make commandline.
A third way to run virt-p2v simulates fairly accurately the program being downloaded over PXE and then doing an automatic conversion of the source physical machine (the non-GUI path -- see next section below):
make run-virt-p2v-non-gui-conversion
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.
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:
;;; In virt-p2v, indent with spaces everywhere (not TABs).
;;; Exceptions: Makefile and ChangeLog modes.
(add-hook 'find-file-hook
'(lambda () (if (and buffer-file-name
(string-match "/virt-p2v\\>"
(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 'c-mode-hook
'(lambda () (if (string-match "/virt-p2v\\>"
(buffer-file-name))
(virt-p2v-c-mode))))
Turn warnings into errors when developing to make warnings hard to ignore:
./configure --enable-werror
Useful targets are:
This is implemented using the regular automake "TESTS" target. See the automake documentation for details.
To mark a test as slow/long-running:
check-slow:
$(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1
When you do "make check-valgrind", it searches for any Makefile.am in the tree that has a "check-valgrind:" target and runs it.
Writing the Makefile.am and tests correctly to use valgrind and working with automake parallel tests is subtle.
If your tests are run via a shell script wrapper, then in the wrapper use:
$VG virt-foo
and in the Makefile.am use:
check-valgrind:
make VG="@VG@" check
However, if your binaries run directly from the "TESTS" rule, you have to modify the Makefile.am like this:
LOG_COMPILER = $(VG)
check-valgrind:
make VG="@VG@" check
In either case, check that the right program is being tested by examining the valgrind* log files carefully.
Submit patches to the mailing list: http://www.redhat.com/mailman/listinfo/libguestfs and CC to rjones@redhat.com.
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.
p2v-building(1), p2v-release-notes(1), http://libguestfs.org/.
Richard W.M. Jones ("rjones at redhat dot com")
Copyright (C) 2009-2019 Red Hat Inc.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
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
To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
When reporting a bug, please supply:
| 2020-05-07 | virt-p2v-1.42.0 |