.\" Automatically generated by Podwrapper::Man 1.32.7 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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 "guestfs-hacking 1"
.TH guestfs-hacking 1 "2016-08-08" "libguestfs-1.32.7" "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"
guestfs\-hacking \- extending and contributing to libguestfs
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This manual page is for hackers who want to extend libguestfs itself.
.SS "\s-1OVERVIEW OF THE SOURCE CODE\s0"
.IX Subsection "OVERVIEW OF THE SOURCE CODE"
Libguestfs source is located in the github repository
https://github.com/libguestfs/libguestfs
.PP
Large amounts of boilerplate code in libguestfs (\s-1RPC,\s0 bindings,
documentation) are generated.  This means that many source files will
appear to be missing from a straightforward git checkout.  You have to
run the generator (\f(CW\*(C`./autogen.sh && make \-C generator\*(C'\fR) in order to
create those files.
.PP
Libguestfs uses an autotools-based build system, with the main files
being \fIconfigure.ac\fR and \fIMakefile.am\fR.  The \fIgenerator\fR
subdirectory contains the generator, plus files describing the \s-1API.\s0
The \fIsrc\fR subdirectory contains source for the library.  The
\&\fIappliance\fR and \fIdaemon\fR subdirectories contain the source for the
code that builds the appliance, and the code that runs in the
appliance respectively.  Other directories are covered in the section
\&\*(L"\s-1SOURCE CODE SUBDIRECTORIES\*(R"\s0 below.
.PP
Apart from the fact that all \s-1API\s0 entry points go via some generated
code, the library is straightforward.  (In fact, even the generated
code is designed to be readable, and should be read as ordinary code).
Some actions run entirely in the library, and are written as C
functions in files under \fIsrc\fR.  Others are forwarded to the daemon
where (after some generated \s-1RPC\s0 marshalling) they appear as C
functions in files under \fIdaemon\fR.
.PP
To build from source, first read the \f(CW\*(C`README\*(C'\fR file.
.SS "\fIlocal*\fP \s-1FILES\s0"
.IX Subsection "local* FILES"
Files in the top source directory that begin with the prefix \fIlocal*\fR
are ignored by git.  These files can contain local configuration or
scripts that you need to build libguestfs.
.PP
By convention, I have a file called \fIlocalconfigure\fR which is a
simple wrapper around \fIautogen.sh\fR containing local configure
customizations that I need:
.PP
.Vb 7
\& . localenv
\& ./autogen.sh \e
\&     \-\-with\-default\-backend=libvirt \e
\&     \-\-enable\-gcc\-warnings \e
\&     \-\-enable\-gtk\-doc \e
\&     \-C \e
\&     "$@"
.Ve
.PP
So I can use this to build libguestfs:
.PP
.Vb 1
\& ./localconfigure && make
.Ve
.PP
If there is a file in the top build directory called \fIlocalenv\fR, then
it will be sourced by \f(CW\*(C`make\*(C'\fR.  This file can contain any local
environment variables needed, eg. for skipping tests:
.PP
.Vb 4
\& # Use an alternate python binary.
\& export PYTHON=python3
\& # Skip this test, it is broken.
\& export SKIP_TEST_BTRFS_FSCK=1
.Ve
.PP
Note that \fIlocalenv\fR is included by the top Makefile (so it's a
Makefile fragment).  But if it is also sourced by your
\&\fIlocalconfigure\fR script then it is used as a shell script.
.SS "\s-1ADDING A NEW API ACTION\s0"
.IX Subsection "ADDING A NEW API ACTION"
Because large amounts of boilerplate code in libguestfs are generated,
this makes it easy to extend the libguestfs \s-1API.\s0
.PP
To add a new \s-1API\s0 action there are two changes:
.IP "1." 4
You need to add a description of the call (name, parameters, return
type, tests, documentation) to \fIgenerator/actions.ml\fR.
.Sp
There are two sorts of \s-1API\s0 action, depending on whether the call goes
through to the daemon in the appliance, or is serviced entirely by the
library (see \*(L"\s-1ARCHITECTURE\*(R"\s0 in \fIguestfs\-internals\fR\|(3)).  \*(L"guestfs_sync\*(R" in \fIguestfs\fR\|(3) is an example
of the former, since the sync is done in the appliance.
\&\*(L"guestfs_set_trace\*(R" in \fIguestfs\fR\|(3) is an example of the latter, since a trace flag
is maintained in the handle and all tracing is done on the library
side.
.Sp
Most new actions are of the first type, and get added to the
\&\f(CW\*(C`daemon_functions\*(C'\fR list.  Each function has a unique procedure number
used in the \s-1RPC\s0 protocol which is assigned to that action when we
publish libguestfs and cannot be reused.  Take the latest procedure
number and increment it.
.Sp
For library-only actions of the second type, add to the
\&\f(CW\*(C`non_daemon_functions\*(C'\fR list.  Since these functions are serviced by
the library and do not travel over the \s-1RPC\s0 mechanism to the daemon,
these functions do not need a procedure number, and so the procedure
number is set to \f(CW\*(C`\-1\*(C'\fR.
.IP "2." 4
Implement the action (in C):
.Sp
For daemon actions, implement the function \f(CW\*(C`do_<name>\*(C'\fR in the
\&\f(CW\*(C`daemon/\*(C'\fR directory.
.Sp
For library actions, implement the function \f(CW\*(C`guestfs_impl_<name>\*(C'\fR
in the \f(CW\*(C`src/\*(C'\fR directory.
.Sp
In either case, use another function as an example of what to do.
.PP
After making these changes, use \f(CW\*(C`make\*(C'\fR to compile.
.PP
Note that you don't need to implement the \s-1RPC,\s0 language bindings,
manual pages or anything else.  It's all automatically generated from
the OCaml description.
.SS "\s-1ADDING TESTS FOR AN API ACTION\s0"
.IX Subsection "ADDING TESTS FOR AN API ACTION"
You can supply zero or as many tests as you want per \s-1API\s0 call.  The
tests can either be added as part of the \s-1API\s0 description
(\fIgenerator/actions.ml\fR), or in some rarer cases you may want to drop
a script into \f(CW\*(C`tests/*/\*(C'\fR.  Note that adding a script to \f(CW\*(C`tests/*/\*(C'\fR
is slower, so if possible use the first method.
.PP
The following describes the test environment used when you add an \s-1API\s0
test in \fIactions.ml\fR.
.PP
The test environment has 4 block devices:
.IP "\fI/dev/sda\fR 2 \s-1GB\s0" 4
.IX Item "/dev/sda 2 GB"
General block device for testing.
.IP "\fI/dev/sdb\fR 2 \s-1GB\s0" 4
.IX Item "/dev/sdb 2 GB"
\&\fI/dev/sdb1\fR is an ext2 filesystem used for testing
filesystem write operations.
.IP "\fI/dev/sdc\fR 10 \s-1MB\s0" 4
.IX Item "/dev/sdc 10 MB"
Used in a few tests where two block devices are needed.
.IP "\fI/dev/sdd\fR" 4
.IX Item "/dev/sdd"
\&\s-1ISO\s0 with fixed content (see \fIimages/test.iso\fR).
.PP
To be able to run the tests in a reasonable amount of time, the
libguestfs appliance and block devices are reused between tests.  So
don't try testing \*(L"guestfs_kill_subprocess\*(R" in \fIguestfs\fR\|(3) :\-x
.PP
Each test starts with an initial scenario, selected using one of the
\&\f(CW\*(C`Init*\*(C'\fR expressions, described in \fIgenerator/types.ml\fR.  These
initialize the disks mentioned above in a particular way as documented
in \fItypes.ml\fR.  You should not assume anything about the previous
contents of other disks that are not initialized.
.PP
You can add a prerequisite clause to any individual test.  This is a
run-time check, which, if it fails, causes the test to be skipped.
Useful if testing a command which might not work on all variations of
libguestfs builds.  A test that has prerequisite of \f(CW\*(C`Always\*(C'\fR means to
run unconditionally.
.PP
In addition, packagers can skip individual tests by setting
environment variables before running \f(CW\*(C`make check\*(C'\fR.
.PP
.Vb 1
\& SKIP_TEST_<CMD>_<NUM>=1
.Ve
.PP
eg: \f(CW\*(C`SKIP_TEST_COMMAND_3=1\*(C'\fR skips test #3 of \*(L"guestfs_command\*(R" in \fIguestfs\fR\|(3).
.PP
or:
.PP
.Vb 1
\& SKIP_TEST_<CMD>=1
.Ve
.PP
eg: \f(CW\*(C`SKIP_TEST_ZEROFREE=1\*(C'\fR skips all \*(L"guestfs_zerofree\*(R" in \fIguestfs\fR\|(3) tests.
.PP
Packagers can run only certain tests by setting for example:
.PP
.Vb 1
\& TEST_ONLY="vfs_type zerofree"
.Ve
.PP
See \fItests/c\-api/tests.c\fR for more details of how these environment
variables work.
.SS "\s-1DEBUGGING NEW API ACTIONS\s0"
.IX Subsection "DEBUGGING NEW API ACTIONS"
Test new actions work before submitting them.
.PP
You can use guestfish to try out new commands.
.PP
Debugging the daemon is a problem because it runs inside a minimal
environment.  However you can fprintf messages in the daemon to
stderr, and they will show up if you use \f(CW\*(C`guestfish \-v\*(C'\fR.
.SS "\s-1ADDING A NEW LANGUAGE BINDING\s0"
.IX Subsection "ADDING A NEW LANGUAGE BINDING"
All language bindings must be generated by the generator
(see the \fIgenerator\fR subdirectory).
.PP
There is no documentation for this yet.  We suggest you look
at an existing binding, eg. \fIgenerator/ocaml.ml\fR or
\&\fIgenerator/perl.ml\fR.
.SS "\s-1ADDING TESTS FOR LANGUAGE BINDINGS\s0"
.IX Subsection "ADDING TESTS FOR LANGUAGE BINDINGS"
Language bindings should come with tests.  Previously testing of
language bindings was rather ad-hoc, but we have been trying to
formalize the set of tests that every language binding should use.
.PP
Currently only the OCaml and Perl bindings actually implement the full
set of tests, and the OCaml bindings are canonical, so you should
emulate what the OCaml tests do.
.PP
This is the numbering scheme used by the tests:
.PP
.Vb 1
\& \- 000+ basic tests:
\& 
\&   010  load the library
\&   020  create
\&   030  create\-flags
\&   040  create multiple handles
\&   050  test setting and getting config properties
\&   060  explicit close
\&   065  implicit close (in GC\*(Aqd languages)
\&   070  optargs
\&   080  version
\& 
\& \- 100  launch, create partitions and LVs and filesystems
\& 
\& \- 400+ events:
\& 
\&   410  close event
\&   420  log messages
\&   430  progress messages
\& 
\& \- 800+ regression tests (specific to the language)
\& 
\& \- 900+ any other custom tests for the language
.Ve
.PP
To save time when running the tests, only 100, 430, 800+, 900+ should
launch the handle.
.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 one of your start-up files
(e.g., ~/.emacs), to help ensure that you get indentation right:
.PP
.Vb 9
\& ;;; In libguestfs, 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 "/libguestfs\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 libguestfs, use this style.
\& (defun libguestfs\-c\-mode ()
\&   "C mode with adjusted defaults for use with libguestfs."
\&   (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 "/libguestfs\e\e>"
\&                               (buffer\-file\-name))
\&                           (libguestfs\-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.
.Sp
See \*(L"\s-1VALGRIND\*(R"\s0 below.
.ie n .IP """make check\-valgrind\-local\-guests""" 4
.el .IP "\f(CWmake check\-valgrind\-local\-guests\fR" 4
.IX Item "make check-valgrind-local-guests"
Runs a subset of the test suite under valgrind
using locally installed libvirt guests (read-only).
.ie n .IP """make check\-direct""" 4
.el .IP "\f(CWmake check\-direct\fR" 4
.IX Item "make check-direct"
Runs all tests using default appliance back-end.  This only
has any effect if a non-default backend was selected
using \f(CW\*(C`./configure \-\-with\-default\-backend=...\*(C'\fR
.ie n .IP """make check\-valgrind\-direct""" 4
.el .IP "\f(CWmake check\-valgrind\-direct\fR" 4
.IX Item "make check-valgrind-direct"
Run a subset of the test suite under valgrind using the
default appliance back-end.
.ie n .IP """make check\-uml""" 4
.el .IP "\f(CWmake check\-uml\fR" 4
.IX Item "make check-uml"
Runs all tests using the User-Mode Linux backend.
.Sp
As there is no standard location for the User-Mode Linux kernel, you
\&\fIhave\fR to set \f(CW\*(C`LIBGUESTFS_HV\*(C'\fR to point to the kernel image, eg:
.Sp
.Vb 1
\& make check\-uml LIBGUESTFS_HV=~/d/linux\-um/vmlinux
.Ve
.ie n .IP """make check\-valgrind\-uml""" 4
.el .IP "\f(CWmake check\-valgrind\-uml\fR" 4
.IX Item "make check-valgrind-uml"
Runs all tests using the User-Mode Linux backend, under valgrind.
.Sp
As above, you have to set \f(CW\*(C`LIBGUESTFS_HV\*(C'\fR to point to the kernel.
.ie n .IP """make check\-with\-upstream\-qemu""" 4
.el .IP "\f(CWmake check\-with\-upstream\-qemu\fR" 4
.IX Item "make check-with-upstream-qemu"
Runs all tests using a local qemu binary.  It looks for the qemu
binary in \s-1QEMUDIR \s0(defaults to \fI\f(CI$HOME\fI/d/qemu\fR), but you can set this
to another directory on the command line, eg:
.Sp
.Vb 1
\& make check\-with\-upstream\-qemu QEMUDIR=/usr/src/qemu
.Ve
.ie n .IP """make check\-with\-upstream\-libvirt""" 4
.el .IP "\f(CWmake check\-with\-upstream\-libvirt\fR" 4
.IX Item "make check-with-upstream-libvirt"
Runs all tests using a local libvirt.  This only has any effect if the
libvirt backend was selected using
\&\f(CW\*(C`./configure \-\-with\-default\-backend=libvirt\*(C'\fR
.Sp
It looks for libvirt in \s-1LIBVIRTDIR \s0(defaults to \fI\f(CI$HOME\fI/d/libvirt\fR),
but you can set this to another directory on the command line, eg:
.Sp
.Vb 1
\& make check\-with\-upstream\-libvirt LIBVIRTDIR=/usr/src/libvirt
.Ve
.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).
.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
.ie n .IP """make check\-all""" 4
.el .IP "\f(CWmake check\-all\fR" 4
.IX Item "make check-all"
Equivalent to running all \f(CW\*(C`make check*\*(C'\fR rules.
.ie n .IP """make check\-release""" 4
.el .IP "\f(CWmake check\-release\fR" 4
.IX Item "make check-release"
Runs a subset of \f(CW\*(C`make check*\*(C'\fR rules that are required to pass
before a tarball can be released.  Currently this is:
.RS 4
.IP "\(bu" 4
check
.IP "\(bu" 4
check-valgrind
.IP "\(bu" 4
check-direct
.IP "\(bu" 4
check-valgrind-direct
.IP "\(bu" 4
check-slow
.RE
.RS 4
.RE
.ie n .IP """make installcheck""" 4
.el .IP "\f(CWmake installcheck\fR" 4
.IX Item "make installcheck"
Run \f(CW\*(C`make check\*(C'\fR on the installed copy of libguestfs.
.Sp
The version of installed libguestfs being tested, and the version of
the libguestfs source tree must be the same.
.Sp
Do:
.Sp
.Vb 4
\& ./autogen.sh
\& make clean ||:
\& make
\& make installcheck
.Ve
.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="$(top_builddir)/run @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 \fItmp/valgrind*\fR log files carefully.
.SS "\s-1DAEMON CUSTOM PRINTF FORMATTERS\s0"
.IX Subsection "DAEMON CUSTOM PRINTF FORMATTERS"
In the daemon code we have created custom printf formatters \f(CW%Q\fR and
\&\f(CW%R\fR, which are used to do shell quoting.
.ie n .IP "%Q" 4
.el .IP "\f(CW%Q\fR" 4
.IX Item "%Q"
Simple shell quoted string.  Any spaces or other shell characters are
escaped for you.
.ie n .IP "%R" 4
.el .IP "\f(CW%R\fR" 4
.IX Item "%R"
Same as \f(CW%Q\fR except the string is treated as a path which is prefixed
by the sysroot.
.PP
For example:
.PP
.Vb 1
\& asprintf (&cmd, "cat %R", path);
.Ve
.PP
would produce \f(CW\*(C`cat /sysroot/some\e path\e with\e spaces\*(C'\fR
.PP
\&\fINote:\fR Do \fInot\fR use these when you are passing parameters to the
\&\f(CW\*(C`command{,r,v,rv}()\*(C'\fR functions.  These parameters do \s-1NOT\s0 need to be
quoted because they are not passed via the shell (instead, straight to
exec).  You probably want to use the \f(CW\*(C`sysroot_path()\*(C'\fR function
however.
.SS "\s-1SUBMITTING YOUR NEW API ACTIONS\s0"
.IX Subsection "SUBMITTING YOUR NEW API ACTIONS"
Submit patches to the mailing list:
http://www.redhat.com/mailman/listinfo/libguestfs
and \s-1CC\s0 to rjones@redhat.com.
.SS "\s-1INTERNATIONALIZATION \s0(I18N) \s-1SUPPORT\s0"
.IX Subsection "INTERNATIONALIZATION (I18N) SUPPORT"
We support i18n (gettext anyhow) in the library.
.PP
However many messages come from the daemon, and we don't translate
those at the moment.  One reason is that the appliance generally has
all locale files removed from it, because they take up a lot of space.
So we'd have to readd some of those, as well as copying our \s-1PO\s0 files
into the appliance.
.PP
Debugging messages are never translated, since they are intended for
the programmers.
.SS "\s-1SOURCE CODE SUBDIRECTORIES\s0"
.IX Subsection "SOURCE CODE SUBDIRECTORIES"
.IP "\fIalign\fR" 4
.IX Item "align"
\&\fIvirt\-alignment\-scan\fR\|(1) command and documentation.
.IP "\fIappliance\fR" 4
.IX Item "appliance"
The libguestfs appliance, build scripts and so on.
.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 "\fIbuilder\fR" 4
.IX Item "builder"
\&\fIvirt\-builder\fR\|(1) command and documentation.
.IP "\fIcat\fR" 4
.IX Item "cat"
The \fIvirt\-cat\fR\|(1), \fIvirt\-filesystems\fR\|(1), \fIvirt\-log\fR\|(1)
and \fIvirt\-ls\fR\|(1) commands and documentation.
.IP "\fIcontrib\fR" 4
.IX Item "contrib"
Outside contributions, experimental parts.
.IP "\fIcustomize\fR" 4
.IX Item "customize"
\&\fIvirt\-customize\fR\|(1) command and documentation.
.IP "\fIdaemon\fR" 4
.IX Item "daemon"
The daemon that runs inside the libguestfs appliance and carries out
actions.
.IP "\fIdf\fR" 4
.IX Item "df"
\&\fIvirt\-df\fR\|(1) command and documentation.
.IP "\fIdib\fR" 4
.IX Item "dib"
\&\fIvirt\-dib\fR\|(1) command and documentation.
.IP "\fIdiff\fR" 4
.IX Item "diff"
\&\fIvirt\-diff\fR\|(1) command and documentation.
.IP "\fIdocs\fR" 4
.IX Item "docs"
Miscellaneous manual pages.
.IP "\fIedit\fR" 4
.IX Item "edit"
\&\fIvirt\-edit\fR\|(1) command and documentation.
.IP "\fIexamples\fR" 4
.IX Item "examples"
C \s-1API\s0 example code.
.IP "\fIfish\fR" 4
.IX Item "fish"
\&\fIguestfish\fR\|(1), the command-line shell, and various shell scripts
built on top such as \fIvirt\-copy\-in\fR\|(1), \fIvirt\-copy\-out\fR\|(1),
\&\fIvirt\-tar\-in\fR\|(1), \fIvirt\-tar\-out\fR\|(1).
.IP "\fIformat\fR" 4
.IX Item "format"
\&\fIvirt\-format\fR\|(1) command and documentation.
.IP "\fIfuse\fR" 4
.IX Item "fuse"
\&\fIguestmount\fR\|(1), \s-1FUSE \s0(userspace filesystem) built on top of libguestfs.
.IP "\fIgenerator\fR" 4
.IX Item "generator"
The crucially important generator, used to automatically generate
large amounts of boilerplate C code for things like \s-1RPC\s0 and bindings.
.IP "\fIget-kernel\fR" 4
.IX Item "get-kernel"
\&\fIvirt\-get\-kernel\fR\|(1) command and documentation.
.IP "\fIgnulib\fR" 4
.IX Item "gnulib"
Gnulib is used as a portability library.  A copy of gnulib is included
under here.
.IP "\fIinspector\fR" 4
.IX Item "inspector"
\&\fIvirt\-inspector\fR\|(1), the virtual machine image inspector.
.IP "\fIlogo\fR" 4
.IX Item "logo"
Logo used on the website.  The fish is called Arthur by the way.
.IP "\fIm4\fR" 4
.IX Item "m4"
M4 macros used by autoconf.
.IP "\fImake-fs\fR" 4
.IX Item "make-fs"
\&\fIvirt\-make\-fs\fR\|(1) command and documentation.
.IP "\fImllib\fR" 4
.IX Item "mllib"
Various libraries and common code used by \fIvirt\-resize\fR\|(1) and
the other tools which are written in OCaml.
.IP "\fIp2v\fR" 4
.IX Item "p2v"
\&\fIvirt\-p2v\fR\|(1) command, documentation and scripts for building the
virt\-p2v \s-1ISO\s0 or disk image.
.IP "\fIpo\fR" 4
.IX Item "po"
Translations of simple gettext strings.
.IP "\fIpo-docs\fR" 4
.IX Item "po-docs"
The build infrastructure and \s-1PO\s0 files for translations of manpages and
\&\s-1POD\s0 files.  Eventually this will be combined with the \fIpo\fR directory,
but that is rather complicated.
.IP "\fIrescue\fR" 4
.IX Item "rescue"
\&\fIvirt\-rescue\fR\|(1) command and documentation.
.IP "\fIresize\fR" 4
.IX Item "resize"
\&\fIvirt\-resize\fR\|(1) command and documentation.
.IP "\fIsparsify\fR" 4
.IX Item "sparsify"
\&\fIvirt\-sparsify\fR\|(1) command and documentation.
.IP "\fIsrc\fR" 4
.IX Item "src"
Source code to the C library.
.IP "\fIsysprep\fR" 4
.IX Item "sysprep"
\&\fIvirt\-sysprep\fR\|(1) command and documentation.
.IP "\fItests\fR" 4
.IX Item "tests"
Tests.
.IP "\fItest-data\fR" 4
.IX Item "test-data"
Files and other test data used by the tests.
.IP "\fItest-tool\fR" 4
.IX Item "test-tool"
Test tool for end users to test if their qemu/kernel combination
will work with libguestfs.
.IP "\fItmp\fR" 4
.IX Item "tmp"
Used for temporary files when running the tests (instead of \fI/tmp\fR
etc).  The reason is so that you can run multiple parallel tests of
libguestfs without having one set of tests overwriting the appliance
created by another.
.IP "\fItools\fR" 4
.IX Item "tools"
Command line tools written in Perl (\fIvirt\-win\-reg\fR\|(1) and many others).
.IP "\fIv2v\fR" 4
.IX Item "v2v"
\&\fIvirt\-v2v\fR\|(1) command and documentation.
.IP "\fIwebsite\fR" 4
.IX Item "website"
The http://libguestfs.org website files.
.IP "\fIcsharp\fR" 4
.IX Item "csharp"
.PD 0
.IP "\fIerlang\fR" 4
.IX Item "erlang"
.IP "\fIgobject\fR" 4
.IX Item "gobject"
.IP "\fIgolang\fR" 4
.IX Item "golang"
.IP "\fIhaskell\fR" 4
.IX Item "haskell"
.IP "\fIjava\fR" 4
.IX Item "java"
.IP "\fIlua\fR" 4
.IX Item "lua"
.IP "\fIocaml\fR" 4
.IX Item "ocaml"
.IP "\fIphp\fR" 4
.IX Item "php"
.IP "\fIperl\fR" 4
.IX Item "perl"
.IP "\fIpython\fR" 4
.IX Item "python"
.IP "\fIruby\fR" 4
.IX Item "ruby"
.PD
Language bindings.
.SS "\s-1MAKING A STABLE RELEASE\s0"
.IX Subsection "MAKING A STABLE RELEASE"
When we make a stable release, there are several steps documented
here.  See \*(L"\s-1LIBGUESTFS VERSION NUMBERS\*(R"\s0 in \fIguestfs\fR\|(3) for general information
about the stable branch policy.
.IP "\(bu" 4
Check \f(CW\*(C`make && make check\*(C'\fR works on at least Fedora, Debian and
Ubuntu.
.IP "\(bu" 4
Check \f(CW\*(C`./configure \-\-without\-libvirt\*(C'\fR works.
.IP "\(bu" 4
Finalize \fIguestfs\-release\-notes.pod\fR
.IP "\(bu" 4
Push and pull from Zanata.
.Sp
Run:
.Sp
.Vb 1
\& zanata push
.Ve
.Sp
to push the latest \s-1POT\s0 files to Zanata.  Then run:
.Sp
.Vb 1
\& ./zanata\-pull.sh
.Ve
.Sp
which is a wrapper to pull the latest translated \fI*.po\fR files.
.IP "\(bu" 4
Consider updating gnulib to latest upstream version.
.IP "\(bu" 4
Create new stable and development directories under
http://libguestfs.org/download.
.IP "\(bu" 4
Edit \fIwebsite/index.html.in\fR.
.IP "\(bu" 4
Set the version (in \fIconfigure.ac\fR) to the new \fIstable\fR version,
ie. 1.XX.0, and commit it:
.Sp
.Vb 6
\& ./localconfigure
\& make distclean \-k
\& ./localconfigure
\& make && make dist
\& make maintainer\-commit
\& make maintainer\-tag
.Ve
.IP "\(bu" 4
Create the stable branch in git:
.Sp
.Vb 2
\& git branch stable\-1.XX
\& git push origin stable\-1.XX
.Ve
.IP "\(bu" 4
Do a full release of the stable branch.
.IP "\(bu" 4
Set the version to the next development version and commit that.
Optionally do a full release of the development branch.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIguestfs\fR\|(3),
\&\fIguestfs\-examples\fR\|(3),
\&\fIguestfs\-internals\fR\|(3),
\&\fIguestfs\-performance\fR\|(1),
\&\fIguestfs\-release\-notes\fR\|(1),
\&\fIguestfs\-testing\fR\|(1),
\&\fIlibguestfs\-test\-tool\fR\|(1),
\&\fIlibguestfs\-make\-fixed\-appliance\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\-2016 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 library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA
02110\-1301 USA\s0
.SH "BUGS"
.IX Header "BUGS"
To get a list of bugs against libguestfs, 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 libguestfs.
.IP "\(bu" 4
Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
.IP "\(bu" 4
Describe the bug accurately and give a way to reproduce it.
.IP "\(bu" 4
Run \fIlibguestfs\-test\-tool\fR\|(1) and paste the \fBcomplete, unedited\fR
output into the bug report.