From b54fa22cd0a6a091324ff1978e0de2c54a0fabde Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Tue, 9 Oct 2012 21:57:54 +0100 Subject: docs: Add overview to guestfs(3)/EXTENDING LIBGUESTFS. --- src/guestfs.pod | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/src/guestfs.pod b/src/guestfs.pod index 0dbc30f1..3194be39 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -3013,11 +3013,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 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 and C. The C +subdirectory contains the generator, plus files describing the API. +The C subdirectory contains source for the library. The +C and C 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 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. Others are forwarded to the daemon +where (after some generated RPC marshalling) they appear as C +functions in files under C. + +To build from source, first read the C 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: -- cgit