From 09eeb04578b90718dfff4f0c6544bd3562cf586d Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Sun, 12 Jun 2016 17:52:52 +0100
Subject: [PATCH] docs: hacking: Document how OCaml programs are compiled and
 linked.

---
 docs/guestfs-hacking.pod | 49 ++++++++++++++++++++++++++++++++++++++++
 ocaml-link.sh            |  7 +++---
 2 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/docs/guestfs-hacking.pod b/docs/guestfs-hacking.pod
index a836ee347..f7e10196a 100644
--- a/docs/guestfs-hacking.pod
+++ b/docs/guestfs-hacking.pod
@@ -713,6 +713,55 @@ into the appliance.
 Debugging messages are never translated, since they are intended for
 the programmers.
 
+=head1 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.
+
+Automake has no native support for OCaml programs, ocamlc nor
+ocamlopt.  What we do instead is to treat OCaml programs as C programs
+which happen to contain these "other objects" (C<"DEPENDENCIES"> in
+automake-speak) that happen to be the OCaml objects.  This works
+because all the OCaml programs contain at least 1 C object used for
+native bindings etc.
+
+So a typical program is described as just its C sources:
+
+ virt_v2v_SOURCES = ... list of C files ...
+
+The OCaml objects which contain most of the code are listed as
+automake dependencies:
+
+ virt_v2v_DEPENDENCIES = ... cmdline.cmx v2v.cmx
+
+The only other special thing we need to do is to provide a custom link
+command.  This is needed because automake won't assemble the ocamlopt
+command, the list of objects and the C<-cclib> libraries in the
+correct order otherwise.
+
+ virt_v2v_LINK = $(top_srcdir)/ocaml-link.sh -cclib ... -- ...
+
+The actual rules, which you can examine in F<v2v/Makefile.am>, are a
+little bit more complicated than this because they have to handle:
+
+=over 4
+
+=item *
+
+Compiling for byte code or native code.
+
+=item *
+
+The pattern rules needed to compile the OCaml sources to objects.
+
+=item *
+
+Adding OCaml sources files to C<EXTRA_DIST>.  Automake isn't aware of
+the complete list of sources for a binary, so it will not add them all
+automatically.
+
+=back
+
 =head1 VIRT-V2V
 
 First a little history.  Virt-v2v has been through at least two
diff --git a/ocaml-link.sh b/ocaml-link.sh
index bbb9b986c..159aa5b64 100755
--- a/ocaml-link.sh
+++ b/ocaml-link.sh
@@ -1,6 +1,5 @@
-#!/bin/bash
-
-# (C) Copyright 2015 Red Hat Inc.
+#!/bin/bash -
+# (C) Copyright 2015-2016 Red Hat Inc.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -16,6 +15,8 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
+# See guestfs-hacking(1) section "HOW OCAML PROGRAMS ARE COMPILED AND LINKED"
+
 # Hack automake to link OCaml-based binaries properly.
 # There is no other way to add the -cclib parameter to the end of
 # the command line.