API doc: document include files and how to build

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in
index 3ed3cac5783bdeac5d542e906be9be00f6d06923..7cff9c7987c8a1a09d7ed904dbec2b034fa87c30 100644 (file)
--- 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 (file)
index 0000000..9c34854
--- /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>
+*/