diff options
Diffstat (limited to 'subprojects/libhandy/doc/build-howto.xml')
| -rw-r--r-- | subprojects/libhandy/doc/build-howto.xml | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/subprojects/libhandy/doc/build-howto.xml b/subprojects/libhandy/doc/build-howto.xml new file mode 100644 index 0000000..a6f731f --- /dev/null +++ b/subprojects/libhandy/doc/build-howto.xml @@ -0,0 +1,159 @@ +<?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>Building</title> + + <para> + If you need to build <application>&package_string;</application>, get the + source from <ulink type="http" url="&package_url;">here</ulink> and see + the <literal>README.md</literal> file. + </para> + </refsect2> + + <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>". + </para> + + <para> + If you use Automake/Autoconf, in your <literal>configure.ac</literal> + script, you might specify something like: + </para> + + <informalexample><programlisting> + PKG_CHECK_MODULES(LIBHANDY, [&package_ver_str;]) + AC_SUBST(LIBHANDY_CFLAGS) + AC_SUBST(LIBHANDY_LIBS) + </programlisting></informalexample> + + <para> + Or when using the Meson build system you can declare a dependency like: + </para> + + <informalexample><programlisting> + dependency('&package_ver_str;') + </programlisting></informalexample> + + <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> + </refsect2> + + <refsect2> + <title>Bundling the library</title> + + <para> + As <application>&package_string;</application> uses the Meson build + system, bundling it as a subproject when it is not installed is easy. + Add this to your <literal>meson.build</literal>: + </para> + + <informalexample><programlisting> + &package_string;_dep = dependency('&package_ver_str;', version: '>= &package_version;', required: false) + if not &package_string;_dep.found() + &package_string; = subproject( + '&package_string;', + install: false, + default_options: [ + 'examples=false', + 'package_subdir=my-project-name', + 'tests=false', + ] + ) + &package_string;_dep = &package_string;.get_variable('&package_string;_dep') + endif + </programlisting></informalexample> + + <para> + Then add &package_string; as a git submodule: + </para> + + <informalexample><programlisting> + git submodule add &package_url;.git subprojects/&package_string; + </programlisting></informalexample> + + <para> + To bundle the library with your Flatpak application, add the following + module to your manifest: + </para> + + <informalexample><programlisting> + { + "name" : "&package_string;", + "buildsystem" : "meson", + "builddir" : true, + "config-opts": [ + "-Dexamples=false", + "-Dtests=false" + ], + "sources" : [ + { + "type" : "git", + "url" : "&package_url;.git" + } + ] + } + </programlisting></informalexample> + </refsect2> + + <refsect2> + <title>Building on macOS</title> + + <para> + To build on macOS you need to install the build-dependencies first. This can e.g. be done via <ulink url="https://brew.sh"><literal>brew</literal></ulink>: + </para> + + <informalexample> + <programlisting> + brew install pkg-config gtk+3 adwaita-icon-theme meson glade gobject-introspection vala + </programlisting> + </informalexample> + + <para> + After running the command above, one may now build the library: + </para> + + <informalexample> + <programlisting> + git clone https://gitlab.gnome.org/GNOME/libhandy.git + cd libhandy + meson . _build + ninja -C _build test + ninja -C _build install + </programlisting> + </informalexample> + + <para> + Working with the library on macOS is pretty much the same as on Linux. To link it, use <literal>pkg-config</literal>: + </para> + + <informalexample> + <programlisting> + gcc $(pkg-config --cflags --libs gtk+-3.0) $(pkg-config --cflags --libs libhandy-1) main.c -o main + </programlisting> + </informalexample> + </refsect2> +</refentry> |