From 968e4792f5d6f2c138a169436672420437630c0f Mon Sep 17 00:00:00 2001
From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Wed, 25 Jan 2017 14:35:09 -0500
Subject: [PATCH] API doc: document include files and how to build
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
---
 doc/api/Doxyfile.in            |  1 +
 doc/api/dox/includes-build.dox | 74 ++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 doc/api/dox/includes-build.dox

diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in
index 3ed3cac5..7cff9c79 100644
--- a/doc/api/Doxyfile.in
+++ b/doc/api/Doxyfile.in
@@ -147,6 +147,7 @@ INPUT                  = "@top_srcdir@/include/babeltrace/ctf-ir" \
                          "@top_srcdir@/include/babeltrace/ref.h" \
                          "@top_srcdir@/include/babeltrace/values.h" \
                          "@srcdir@/dox/main-page.dox" \
+                         "@srcdir@/dox/includes-build.dox" \
                          "@srcdir@/dox/write-plugin.dox" \
                          "@srcdir@/dox/use-ctf-writer.dox" \
                          "@srcdir@/dox/examples.dox" \
diff --git a/doc/api/dox/includes-build.dox b/doc/api/dox/includes-build.dox
new file mode 100644
index 00000000..9c348541
--- /dev/null
+++ b/doc/api/dox/includes-build.dox
@@ -0,0 +1,74 @@
+/**
+@page includesbuild Include files and how to build
+
+@section includefiles Include files
+
+You can find all the Babeltrace library include files (C headers) in the
+\c babeltrace directory under the include files directory chosen when
+installing Babeltrace. By default, this is <code>/usr/include</code>.
+If you build Babeltrace from source without specifying an installation
+prefix, this is <code>/usr/local/include</code>.
+
+The documentation modules in \ref apiref always show which header file
+to include to use the documented functions and types.
+
+You can also use the "master" include file which provides everything,
+but which necessarily makes the compilation slower:
+
+@code
+#include <babeltrace/babeltrace.h>
+@endcode
+
+@section howtobuild How to build
+
+Multiple types of applications can use the Babeltrace library:
+
+- A user plugin (shared object) to be loaded by the \c babeltrace
+  converter program or by another application.
+- A user application or library which loads plugins to manually connect
+  existing components in a specific way.
+- A user application or library which creates its own component classes
+  and manually connects them.
+
+In any way, the only library to link to is `libbabeltrace`.
+
+@subsection howtobuildplugin Build a plugin
+
+To build a user plugin:
+
+<ol>
+    <li>Compile the source files which form your plugin:
+
+@verbatim
+cc -c -fpic my-plugin.c
+@endverbatim
+    </li>
+
+    <li>Create the plugin shared object:
+
+@verbatim
+cc -shared my-plugin.o -lbabeltrace -o my-plugin.so
+@endverbatim
+    </li>
+</ol>
+
+@subsection howtobuildapp Build an application
+
+To build an application which uses the Babeltrace library:
+
+<ol>
+    <li>Compile the source files which form your application:
+
+@verbatim
+cc -c my-app.c
+@endverbatim
+    </li>
+
+    <li>Create the executable application:
+
+@verbatim
+cc my-app.o -lbabeltrace -o my-app
+@endverbatim
+    </li>
+</ol>
+*/
-- 
2.34.1