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.

bash

Bash tab-completion scripts.

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.

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.

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

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

UNDERSTANDING THE CODE¶

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)

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.

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:

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.

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.

SUBMITTING PATCHES¶

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.