[Libguestfs] [p2v PATCH 3/4] Import some internal documentation

Import the general building & hacking documentation from libguestfs, adapting them to virt-p2v (i.e. with only pieces of information relevant to it, and to its current sources). Adjust the references to these new documentations. Add also a skeleton of release notes document. --- .gitignore | 6 + Makefile.am | 4 +- configure.ac | 1 + docs/Makefile.am | 65 ++++++++ docs/p2v-building.pod | 259 ++++++++++++++++++++++++++++++++ docs/p2v-hacking.pod | 293 +++++++++++++++++++++++++++++++++++++ docs/p2v-release-notes.pod | 47 ++++++ run.in | 2 +- test-functions.sh | 2 +- virt-p2v-make-disk.in | 2 +- virt-p2v-make-disk.pod | 2 +- 11 files changed, 678 insertions(+), 5 deletions(-) create mode 100644 docs/Makefile.am create mode 100644 docs/p2v-building.pod create mode 100644 docs/p2v-hacking.pod create mode 100644 docs/p2v-release-notes.pod diff --git a/.gitignore b/.gitignore index a81b59a..459c9a0 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,12 @@ Makefile.in /dependencies.debian /dependencies.redhat /dependencies.suse +/docs/p2v-building.1 +/docs/p2v-hacking.1 +/docs/p2v-release-notes.1 +/docs/stamp-p2v-building.pod +/docs/stamp-p2v-hacking.pod +/docs/stamp-p2v-release-notes.pod /fedora.img /gnulib/ /kernel-config.c diff --git a/Makefile.am b/Makefile.am index 2d0178c..31c54c0 100644 --- a/Makefile.am +++ b/Makefile.am @@ -24,6 +24,8 @@ if ENABLE_GNULIB_TESTS SUBDIRS += gnulib/tests endif +SUBDIRS += docs + # bash-completion SUBDIRS += bash @@ -248,7 +250,7 @@ stamp-virt-p2v-make-kiwi.pod: virt-p2v-make-kiwi.pod touch $@ # Run virt-p2v locally either directly or in a VM. -# See guestfs-hacking(1) section "Running virt-p2v" +# See p2v-hacking(1) section "Running virt-p2v" PHYSICAL_MACHINE = $(abs_builddir)/fedora.img BLANK_DISK = blank-part.img diff --git a/configure.ac b/configure.ac index aeb50a6..f98cb1b 100644 --- a/configure.ac +++ b/configure.ac @@ -105,6 +105,7 @@ AC_CONFIG_FILES([run], AC_CONFIG_FILES([Makefile bash/Makefile + docs/Makefile gnulib/lib/Makefile gnulib/tests/Makefile]) diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..9ad83aa --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,65 @@ +# libguestfs documentation +# Copyright (C) 2010-2019 Red Hat Inc. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program 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 General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +include $(top_srcdir)/subdir-rules.mk + +EXTRA_DIST = \ + p2v-building.pod \ + p2v-hacking.pod \ + p2v-release-notes.pod + +man_MANS = \ + p2v-building.1 \ + p2v-hacking.1 \ + p2v-release-notes.1 +noinst_DATA = \ + $(top_builddir)/website/p2v-building.1.html \ + $(top_builddir)/website/p2v-hacking.1.html \ + $(top_builddir)/website/p2v-release-notes.1.html + +p2v-building.1 $(top_builddir)/website/p2v-building.1.html: stamp-p2v-building.pod + +stamp-p2v-building.pod: p2v-building.pod + $(PODWRAPPER) \ + --section 1 \ + --man p2v-building.1 \ + --html $(top_builddir)/website/p2v-building.1.html \ + --license LGPLv2+ \ + $< + touch $@ + +p2v-hacking.1 $(top_builddir)/website/p2v-hacking.1.html: stamp-p2v-hacking.pod + +stamp-p2v-hacking.pod: p2v-hacking.pod + $(PODWRAPPER) \ + --section 1 \ + --man p2v-hacking.1 \ + --html $(top_builddir)/website/p2v-hacking.1.html \ + --license LGPLv2+ \ + $< + touch $@ + +p2v-release-notes.1 $(top_builddir)/website/p2v-release-notes.1.html: stamp-p2v-release-notes.pod + +stamp-p2v-release-notes.pod: p2v-release-notes.pod + $(PODWRAPPER) \ + --section 1 \ + --man p2v-release-notes.1 \ + --html $(top_builddir)/website/p2v-release-notes.1.html \ + --license GPLv2+ \ + $< + touch $@ diff --git a/docs/p2v-building.pod b/docs/p2v-building.pod new file mode 100644 index 0000000..0e3df94 --- /dev/null +++ b/docs/p2v-building.pod @@ -0,0 +1,259 @@ +=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&lt;rich(a)annexia.org&gt;, +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. diff --git a/docs/p2v-hacking.pod b/docs/p2v-hacking.pod new file mode 100644 index 0000000..cdc6c89 --- /dev/null +++ b/docs/p2v-hacking.pod @@ -0,0 +1,293 @@ +=head1 NAME + +p2v-hacking - extending and contributing to virt-p2v + +=head1 DESCRIPTION + +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. + +=head1 THE SOURCE CODE + +Virt-p2v source is located in the github repository +L<https://github.com/libguestfs/virt-p2v> + +Virt-p2v uses an autotools-based build system, with the main files +being F<configure.ac> and F<Makefile.am>. See L</THE BUILD SYSTEM>. + +To build from source, first read the L<p2v-building(1)>. + +=head2 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. + +=over 4 + +=item F<bash> + +Bash tab-completion scripts. + +=item F<build-aux> + +Various build scripts used by autotools. + +=item F<miniexpect> + +A copy of the miniexpect library from +L<http://git.annexia.org/?p=miniexpect.git;a=summary>. + +=item F<contrib> + +Outside contributions, experimental parts. + +=item F<docs> + +Miscellaneous manual pages. + +=item F<gnulib> + +Gnulib is used as a portability library. A copy of gnulib is included +under here. + +=item F<libguestfs> + +Some sources (mostly with utilities) copied from libguestfs. Changes +to the sources there ought to be forwarded to libguestfs as well. + +=item F<m4> + +M4 macros used by autoconf. See L</THE BUILD SYSTEM>. + +=item F<website> + +The virt-p2v files of the L<http://libguestfs.org> website. + +=back + +=head2 THE BUILD SYSTEM + +Virt-p2v uses the GNU autotools build system (autoconf, automake). + +The F<./configure> script is generated from F<configure.ac> and +F<m4/p2v-*.m4>. Most of the configure script is split over many +m4 macro files by topic, for example F<m4/p2v-libraries.m4> deals +with the libraries required by virt-p2v. + +F<subdir-rules.mk> is included in every F<Makefile.am> (top level and +subdirectories). + +=head2 UNDERSTANDING THE CODE + +I<See also:> L<virt-p2v(1)/HOW VIRT-P2V WORKS> + +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 F<conversion.c> function +C<start_conversion> to run the remote virt-v2v. + +The main task of F<gui.c>/F<kernel.c> is to populate the virt-v2v +configuration (F<config.c>). + +During conversion, we need to establish ssh connections, and that is +done using two libraries: + + conversion.c ──────▶ ssh.c ──────▶ miniexpect.c + +where F<ssh.c> is responsible for managing ssh connections overall, +and F<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: +F<http://git.annexia.org/?p=miniexpect.git;a=summary>) + +=head1 RUNNING VIRT-P2V + +You can run the F<virt-p2v> binary directly, but it will try to +convert your machine’s real F</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 L<virt-p2v(1)> I<--test-disk> option. +You can control the "physical machine" disk by setting +C<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 C<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 C<QEMU> and/or C<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 + +=head1 EXTENDING VIRT-P2V + +=head2 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)))) + +=head2 TESTING YOUR CHANGES + +Turn warnings into errors when developing to make warnings hard to +ignore: + + ./configure --enable-werror + +Useful targets are: + +=over 4 + +=item C<make check> + +Runs the regular test suite. + +This is implemented using the regular automake C<TESTS> target. See +the automake documentation for details. + +=item C<make check-valgrind> + +Runs a subset of the test suite under valgrind. + +=item C<make check-slow> + +Runs some slow/long-running tests which are not run by default. + +To mark a test as slow/long-running: + +=over 4 + +=item * + +Add it to the list of C<TESTS> in the F<Makefile.am>, just like a +normal test. + +=item * + +Modify the test so it checks if the C<SLOW=1> environment variable is +set, and if I<not> set it skips (ie. returns with exit code 77). If +using C<$TEST_FUNCTIONS>, you can call the function C<slow_test> for +this. + +=item * + +Add a variable C<SLOW_TESTS> to the F<Makefile.am> listing the slow +tests. + +=item * + +Add a rule to the F<Makefile.am>: + + check-slow: + $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1 + +=back + +=back + +=head2 VALGRIND + +When you do C<make check-valgrind>, it searches for any F<Makefile.am> +in the tree that has a C<check-valgrind:> target and runs it. + +Writing the F<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 F<Makefile.am> use: + + check-valgrind: + make VG="@VG@" check + +However, if your binaries run directly from the C<TESTS> rule, you +have to modify the F<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 F<valgrind*> log files carefully. + +=head2 SUBMITTING PATCHES + +Submit patches to the mailing list: +L<http://www.redhat.com/mailman/listinfo/libguestfs> +and CC to L&lt;rjones(a)redhat.com&gt;. + +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. + +=head1 SEE ALSO + +L<p2v-building(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. diff --git a/docs/p2v-release-notes.pod b/docs/p2v-release-notes.pod new file mode 100644 index 0000000..ee0dd98 --- /dev/null +++ b/docs/p2v-release-notes.pod @@ -0,0 +1,47 @@ +=head1 NAME + +p2v-release-notes - virt-p2v Release Notes + +=begin comment + +UPDATED TO <commit id> + +=end comment + +=begin comment + +<script> +document.body.style.backgroundImage = "url('draft.png')"; +document.body.style.backgroundRepeat = "no-repeat"; +</script> + +=end comment + +=head1 RELEASE NOTES FOR VIRT-P2V 1.XX + +These release notes only cover the differences from the previous +stable/dev branch split (1.40.0). For detailed changelogs, please see +the git repository, or the ChangeLog file distributed in the tarball. + +... + +=for comment ################################################################ + +=head1 RELEASE NOTES FOR HISTORICAL VERSIONS OF VIRT-P2V + +Before 1.XX virt-p2v was released as part of libguestfs. Therefore, +release notes for these older versions are found as part of the +L<release notes of libguestfs|guestfs-release-notes(1)>. + +=head1 SEE ALSO + +L<guestfs-release-notes(1)>, +L<http://libguestfs.org/> + +=head1 AUTHOR + +Richard W.M. Jones + +=head1 COPYRIGHT + +Copyright (C) 2009-2019 Red Hat Inc. diff --git a/run.in b/run.in index a3def1d..fbb1247 100755 --- a/run.in +++ b/run.in @@ -29,7 +29,7 @@ # and programs in the libguestfs distribution. # # For lots more ways to use this script, see the libguestfs -# guestfs-building(1) man page. +# p2v-building(1) man page. # # The script should also be used for tests like this: # diff --git a/test-functions.sh b/test-functions.sh index 609b356..1b5ac00 100755 --- a/test-functions.sh +++ b/test-functions.sh @@ -110,7 +110,7 @@ skip_unless () fi } -# Slow tests should always call this function. (See guestfs-hacking(1)). +# Slow tests should always call this function. (See p2v-hacking(1)). slow_test () { if [ -z "$SLOW" ]; then diff --git a/virt-p2v-make-disk.in b/virt-p2v-make-disk.in index 4cf8f56..e353f3f 100644 --- a/virt-p2v-make-disk.in +++ b/virt-p2v-make-disk.in @@ -145,7 +145,7 @@ if [ ! -f "$virt_p2v_xz_binary" ]; then if [ -n "$arch" ]; then echo "You used the '--arch' option, so it’s likely that you will need to build" echo "a virt-p2v.$arch binary yourself." - echo "See guestfs-building(1) section BUILDING i686 32 BIT VIRT-P2V for help." + echo "See p2v-building(1) section BUILDING i686 32 BIT VIRT-P2V for help." fi exit 1 fi diff --git a/virt-p2v-make-disk.pod b/virt-p2v-make-disk.pod index 05b8a3d..a15aaad 100644 --- a/virt-p2v-make-disk.pod +++ b/virt-p2v-make-disk.pod @@ -109,7 +109,7 @@ usually F<virt-p2v.i686>) by some means, and that you install it next to the ordinary F<virt-p2v> binary (eg. in F<$libdir/virt-p2v/> or C<$VIRT_V2V_DATA_DIR>). This is outside the scope of this manual page, but you can find some tips in -L<guestfs-building(1)/BUILDING i686 32 BIT VIRT-P2V>. +L<p2v-building(1)/BUILDING i686 32 BIT VIRT-P2V>. =head1 OPTIONS -- 2.21.0