<?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>
