diff options
author | Richard W.M. Jones <rjones@redhat.com> | 2012-10-09 21:57:54 +0100 |
---|---|---|
committer | Richard W.M. Jones <rjones@redhat.com> | 2012-10-30 18:24:01 +0000 |
commit | 8ebb9b17150ddfabc510aecf97c5f99d9334bb25 (patch) | |
tree | 597bb118036b048e1ba1af7e86e980c826eb65a8 /src | |
parent | 11add089449249d1e6d7e7de333184a754247991 (diff) | |
download | libguestfs-8ebb9b17150ddfabc510aecf97c5f99d9334bb25.tar.gz libguestfs-8ebb9b17150ddfabc510aecf97c5f99d9334bb25.tar.xz libguestfs-8ebb9b17150ddfabc510aecf97c5f99d9334bb25.zip |
docs: Add overview to guestfs(3)/EXTENDING LIBGUESTFS.
(cherry picked from commit b54fa22cd0a6a091324ff1978e0de2c54a0fabde)
(cherry picked from commit 52cc8c455e429aa5cc9f5218cb9b939edf3b95b1)
Diffstat (limited to 'src')
-rw-r--r-- | src/guestfs.pod | 37 |
1 files changed, 34 insertions, 3 deletions
diff --git a/src/guestfs.pod b/src/guestfs.pod index fe386d44..12a04334 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -2777,11 +2777,42 @@ time. =head1 EXTENDING LIBGUESTFS -=head2 ADDING A NEW API ACTION +This section is for hackers who want to extend libguestfs itself. + +=head2 OVERVIEW OF THE SOURCE CODE + +Libguestfs source is located in the github repository +L<https://github.com/libguestfs/libguestfs> Large amounts of boilerplate code in libguestfs (RPC, bindings, -documentation) are generated, and this makes it easy to extend the -libguestfs API. +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 (C<./autogen.sh && make -C generator>) in order to +create those files. + +Libguestfs uses an autotools-based build system, with the main files +being C<configure.ac> and C<Makefile.am>. The C<generator> +subdirectory contains the generator, plus files describing the API. +The C<src> subdirectory contains source for the library. The +C<appliance> and C<daemon> 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<SOURCE CODE SUBDIRECTORIES> below. + +Apart from the fact that all API 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 C<src>. Others are forwarded to the daemon +where (after some generated RPC marshalling) they appear as C +functions in files under C<daemon>. + +To build from source, first read the C<README> file. + +=head2 ADDING A NEW API ACTION + +Because large amounts of boilerplate code in libguestfs are generated, +this makes it easy to extend the libguestfs API. To add a new API action there are two changes: |