diff --git a/docs/guestfs-hacking.pod b/docs/guestfs-hacking.pod index 6d6458ba5..f4ed07d4a 100644 --- a/docs/guestfs-hacking.pod +++ b/docs/guestfs-hacking.pod @@ -6,7 +6,7 @@ guestfs-hacking - extending and contributing to libguestfs This manual page is for hackers who want to extend libguestfs itself. -=head1 OVERVIEW OF THE SOURCE CODE +=head1 THE SOURCE CODE Libguestfs source is located in the github repository L @@ -37,7 +37,7 @@ functions in files under F. To build from source, first read the L. -=head1 SOURCE CODE SUBDIRECTORIES +=head2 SOURCE CODE SUBDIRECTORIES There are a lot of subdirectories in the source tree! Which ones should you concentrate on first? F and F which contain @@ -316,7 +316,7 @@ Language bindings. =back -=head1 THE BUILD SYSTEM +=head2 THE BUILD SYSTEM Libguestfs uses the GNU autotools build system (autoconf, automake, libtool). @@ -337,7 +337,9 @@ There are many make targets. Use this command to list them all: make help -=head1 ADDING A NEW API +=head1 EXTENDING LIBGUESTFS + +=head2 ADDING A NEW API Because large amounts of boilerplate code in libguestfs are generated, this makes it easy to extend the libguestfs API. @@ -392,7 +394,7 @@ Note that you don't need to implement the RPC, language bindings, manual pages or anything else. It's all automatically generated from the OCaml description. -=head2 Adding tests for an API +=head3 Adding tests for an API You can supply zero or as many tests as you want per API call. The tests can either be added as part of the API description @@ -462,7 +464,7 @@ Packagers can run only certain tests by setting for example: See F for more details of how these environment variables work. -=head2 Debugging new APIs +=head3 Debugging new APIs Test new actions work before submitting them. @@ -472,7 +474,7 @@ 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 C. -=head1 ADDING A NEW LANGUAGE BINDING +=head2 ADDING A NEW LANGUAGE BINDING All language bindings must be generated by the generator (see the F subdirectory). @@ -481,7 +483,7 @@ There is no documentation for this yet. We suggest you look at an existing binding, eg. F or F. -=head2 Adding tests for language bindings +=head3 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 @@ -521,7 +523,7 @@ This is the numbering scheme used by the tests: To save time when running the tests, only 100, 430, 800+, 900+ should launch the handle. -=head1 FORMATTING CODE +=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 @@ -554,7 +556,7 @@ If you use Emacs, add the following to one of one of your start-up files (buffer-file-name)) (libguestfs-c-mode)))) -=head1 TESTING YOUR CHANGES +=head2 TESTING YOUR CHANGES Turn warnings into errors when developing to make warnings hard to ignore: @@ -775,7 +777,7 @@ have to modify the F like this: In either case, check that the right program is being tested by examining the F log files carefully. -=head1 SUBMITTING PATCHES +=head2 SUBMITTING PATCHES Submit patches to the mailing list: L @@ -784,7 +786,7 @@ and CC to L. 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 DAEMON CUSTOM PRINTF FORMATTERS +=head2 DAEMON CUSTOM PRINTF FORMATTERS In the daemon code we have created custom printf formatters C<%Q> and C<%R>, which are used to do shell quoting. @@ -815,7 +817,7 @@ quoted because they are not passed via the shell (instead, straight to exec). You probably want to use the C function however. -=head1 INTERNATIONALIZATION (I18N) SUPPORT +=head2 INTERNATIONALIZATION (I18N) SUPPORT We support i18n (gettext anyhow) in the library. @@ -828,7 +830,9 @@ into the appliance. Debugging messages are never translated, since they are intended for the programmers. -=head1 HOW OCAML PROGRAMS ARE COMPILED AND LINKED +=head1 MISCELLANEOUS TOPICS + +=head2 HOW OCAML PROGRAMS ARE COMPILED AND LINKED Mostly this section is "how we make automake & ocamlopt work together" since OCaml programs themselves are easy to compile. @@ -886,7 +890,7 @@ it will not add them all automatically. =back -=head1 VIRT-V2V +=head2 VIRT-V2V First a little history. Virt-v2v has been through at least two complete rewrites, so this is probably about the third version (but we @@ -929,7 +933,7 @@ Every other file in this directory is a support module / library of some sort. Some code is written in C, especially where we want to use an external C library such as libxml2. -=head1 VIRT-P2V +=head2 VIRT-P2V 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 @@ -938,7 +942,7 @@ 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. -=head2 Running virt-p2v +=head3 Running virt-p2v You can run the F binary directly, but it will try to convert your machine's real F which is unlikely to work @@ -969,7 +973,7 @@ below): make -C p2v run-virt-p2v-non-gui-conversion -=head2 Understanding the virt-p2v code +=head3 Understanding the virt-p2v code I L @@ -1001,7 +1005,9 @@ if you patch miniexpect.c, then please make sure the changes get reflected in miniexpect's upstream too: F) -=head1 MAKING A STABLE RELEASE +=head1 MAINTAINER TASKS + +=head2 MAKING A STABLE RELEASE When we make a stable release, there are several steps documented here. See L for general information