README
======

The public interface is described in 'libvirt.mli'.  You may prefer to
do 'make doc' at the top level source directory and then read the HTML
documentation starting at html/index.html.

'libvirt.ml' describes how OCaml functions map to C functions.

'libvirt_c*.c' are the C functions which map OCaml objects to C
objects and vice versa (see next section).

Generated code
--------------

The C bindings in 'libvirt_c.c' are now generated automatically by a
Perl script called 'generator.pl'.  You do not normally need to run
this script, but you may need to if you want to extend libvirt
coverage.

The majority of the functions are now generated automatically, but
there are a few one-off bindings (eg. one-of-a-type functions,
functions with particularly complex mappings).  Our eventual aim to is
autogenerate as much as possible.  Use 'make autostatus' in this
directory to find out how we're doing.

The generated 'libvirt_c.c' #includes some other C files in this
directory:

  #include "libvirt_c_prologue.c"

    A prologue that prototypes some static functions which are defined
    in the epilogue (see below), and provides some general macros.

  #include "libvirt_c_oneoffs.c"

    One-off bindings: Bindings which are too specialised or one-of-a-kind
    to be worth generating automatically.

  [Followed by generated bindings, then ...]

  #include "libvirt_c_epilogue.c"

    An epilogue which defines some standard static functions (eg.) for
    wrapping and unwrapping libvirt objects.

The key to understanding the generator is to look at the generated
code (libvirt_c.c) first, and go from there back to parts of the
generator script.
