p2v-hacking(1)

📦
version 1.42.4 · 7 versions
, in ubuntu stonking

💖 p2v-hacking(1) — the "extend virt-p2v and be iconic" manual 💖

okay bestie, so this is p2v-hacking(1), from the Virtualization Support manual. it's the whole vibe of "how do i hack on virt-p2v itself" and honestly? slay. let's get into it 🫶

✨ NAME ✨

p2v-hacking — extending and contributing to virt-p2v

🌸 DESCRIPTION 🌸

so this page is for the hackers who wanna extend virt-p2v itself. that's you, main character. 💅

okay so here's the tea: virt-p2v is literally just a front end on virt-v2v. like. all it does is act as a GUI front end, and then it calls out to virt-v2v to do the actual conversion. so most of the C code is Gtk (that's GUI) code, or supporting code for talking to the remote conversion server. and ngl there is no special support for physical machines in virt-v2v — they get converted in the exact same way as foreign VMs. periodt. 🦋

🎀 THE SOURCE CODE 🎀

the virt-p2v source is chillin' in the github repository at https://github.com/libguestfs/virt-p2v ✨

virt-p2v uses an autotools-based build system, and the main files are configure.ac and Makefile.am. more on that in "THE BUILD SYSTEM" below, iykyk.

want to build from source? first read p2v-building(1), bestie. 🔥

💫 SOURCE CODE SUBDIRECTORIES 💫

so the majority of the source code is directly in the top level directory of the sources. but there are also some subdirectories holding specific sub-parts of virt-p2v, and they're all kind of iconic in their own way:

  • bash — bash tab-completion scripts. so your shell can be psychic. ✨
  • build-aux — various build scripts used by autotools.
  • miniexpect — a copy of the miniexpect library from http://git.annexia.org/?p=miniexpect.git;a=summary.
  • contrib — outside contributions, experimental parts. the chaotic corner, we love her. 💀
  • docs — miscellaneous manual pages.
  • libguestfs — some sources (mostly with utilities) copied from libguestfs. changes to the sources there ought to be forwarded to libguestfs as well — don't be sneaky, bestie. 👀
  • m4 — M4 macros used by autoconf. see "THE BUILD SYSTEM".
  • website — the virt-p2v files of the http://libguestfs.org website.

🛠️ THE BUILD SYSTEM 🛠️

virt-p2v uses the GNU autotools build system (autoconf, automake). old money. 💅

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 — like, for example, m4/p2v-libraries.m4 deals with the libraries required by virt-p2v. cute and organized. 🎀

subdir-rules.mk is included in every Makefile.am (top level and subdirectories). everywhere. all at once. ✨

👑 UNDERSTANDING THE CODE 👑

see also: "HOW VIRT-P2V WORKS" in virt-p2v(1)

okay so there are two paths through the code — GUI, or non-GUI (which is parsing the kernel command line):

 main.c ──────┬─────▶ gui.c ──────┬─────▶ conversion.c
              │                   │
              │                   │
              └────▶ kernel.c ────┘

but here's the thing — both paths call back to the conversion.c function start_conversion to run the remote virt-v2v. two paths, one destiny. 🌈

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's 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. bestie behavior. 🫶

(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) — seriously, don't leave upstream hanging, that's not the vibe. 😭

🚀 RUNNING VIRT-P2V 🚀

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. 💀 so maybe don't. 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. obsessed. ✨

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
 make run-virt-p2v-in-an-nvme-vm

these also run 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. the second target exposes the "physical machine" 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 QEMU and/or QEMU_OPTIONS on the make commandline. so much power. 🌸

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 (that's the non-GUI path — see next section below):

 make run-virt-p2v-non-gui-conversion

💖 EXTENDING VIRT-P2V 💖

🎨 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. no cap. 💅

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))))

🧪 TESTING YOUR CHANGES 🧪

turn warnings into errors when developing, to make warnings hard to ignore:

 ./configure --enable-werror

useful targets are:

  • make check — runs the regular test suite.
    • this is implemented using the regular automake TESTS target. see the automake documentation for details.
  • make check-valgrind — runs a subset of the test suite under valgrind.
  • make check-slow — runs some slow/long-running tests which are not run by default.
    • to mark a test as slow/long-running:
      1. add it to the list of TESTS in the Makefile.am, just like a normal test.
      2. modify the test so it checks if the SLOW=1 environment variable is set, and if not set it skips (ie. returns with exit code 77). if using $TEST_FUNCTIONS, you can call the function slow_test for this.
      3. add a variable SLOW_TESTS to the Makefile.am listing the slow tests.
      4. add a rule to the Makefile.am:
 check-slow:
   $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1

🔍 VALGRIND 🔍

when you do make check-valgrind, it searches for any Makefile.am in the tree that has a check-valgrind: target and runs it.

ngl, writing the Makefile.am and tests correctly to use valgrind and working with automake parallel tests is subtle. it's giving "trust the process". 😭

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. look with your eyes, bestie. 👀

📬 SUBMITTING PATCHES 📬

submit patches to the mailing list: https://lists.libguestfs.org 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. no biggie, we wait. 🧚

🌈 SEE ALSO 🌈

p2v-building(1), p2v-release-notes(1), http://libguestfs.org/.

⭐ AUTHORS ⭐

Richard W.M. Jones ("rjones at redhat dot com") — the icon, the legend, the moment. 👑

Copyright (C) 2009-2019 Red Hat Inc.

📜 LICENSE 📜

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/.

fr fr, no warranty, so pls don't come for us if it goes sideways. 🙈

🐛 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

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:

  • the version of virt-p2v.
  • where you got virt-p2v (eg. which Linux distro, compiled from source, etc)
  • describe the bug accurately and give a way to reproduce it.

and that's the whole page, bestie!! this was virt-p2v-1.42.4, dated 2026-04-08 — go forth and hack, the codebase is literally waiting for you 💅✨🦋

📦 where this page comes from