Initial commit

Signed-off-by: Guido Günther <agx@sigxcpu.org>
2020-02-14 17:40:34 +01:00
commit 3663b7d149
83 changed files with 8059 additions and 0 deletions
@@ -0,0 +1,89 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+  %gtkdocentities;
+]>
+
+<refentry id="build-howto">
+  <refmeta>
+    <refentrytitle>Compiling with &package_string;</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Compiling with &package_string;</refname><refpurpose>Notes on compiling</refpurpose>
+  </refnamediv>
+
+  <refsect2>
+    <title>Using pkg-config</title>
+
+    <para> Like other GNOME libraries,
+    <application>&package_string;</application> uses
+    <application>pkg-config</application> to provide compiler options. The
+    package name is
+    "<literal>&package_ver_str;</literal>". So in
+    your <literal>configure.ac</literal> script, you might specify something
+    like: </para>
+
+    <informalexample><programlisting>
+      PKG_CHECK_MODULES(LIBFEEDBACK, [&package_string;-&package_api_version;])
+      AC_SUBST(LIBFEEDBACK_CFLAGS)
+      AC_SUBST(LIBFEEDBACK_LIBS)
+    </programlisting></informalexample>
+
+    <para>
+      Or if using Meson/Ninja use a <literal>dependency('&package_string;-&package_api_version;')
+    </literal> dependency.
+    </para>
+
+    <para>
+      The "<literal>&package_api_version;</literal>" in the package name is the "API version"
+      (indicating "the version of the <application>&package_string;</application> API
+      that first appeared in version &package_api_version;") and is essentially just part of
+      the package name.
+    </para>
+
+    <para>
+      When using the Meson build system you can declare a dependency like
+    </para>
+    <informalexample><programlisting>
+      dependency(libfeedback-0.0')
+    </programlisting></informalexample>
+
+  </refsect2>
+
+  <refsect2>
+    <title>Acknowledge the Instability</title>
+
+    <para>
+      Since the library is young and is still changing a lot, in order to use it you are required to acknowledge that your are using an unstable API.
+      To do so, <literal>LIBFEEDBACK_USE_UNSTABLE_API</literal> must be defined for compilation to succeed.
+    </para>
+
+    <para>
+      From C code or any compatible language, you can prefix your inclusion of the &package_string; header like so:
+    </para>
+
+    <informalexample><programlisting>
+      #define LIBFEEDBACK_USE_UNSTABLE_API
+      #include &lt;libfeedback.h&gt;
+    </programlisting></informalexample>
+
+    <para>
+      Including individual headers rather than <literal>libfeedback.h</literal> is not
+      recommended.
+    </para>
+    <para>
+      You can also acknoledge this with the definition option of your C compiler, like <literal>-DFEEDBACK_USE_UNSTABLE_API</literal>.
+      This is required from Vala.
+    </para>
+
+    <para>
+      To use &package_name; from Vala, you must define the acknowledgment in C via <literal>-X -DFEEDBACK_USE_UNSTABLE_API</literal>.
+      If your build system uses a two pass compilation and hence your Vala compiler outputs C (Meson, Automake, or using the <literal>--ccode</literal> Vala compiler option trigger that) then you must add <literal>-DLIBFEEDBACK_USE_UNSTABLE_API</literal> to your C compiler argments instead.
+    </para>
+  </refsect2>
+
+</refentry>