## Compiling with libhandy

Compiling with libhandy — Notes on compiling.

### Building

If you need to build libhandy, get the source from here and see the `README.md` file.

### Using pkg-config

Like other GNOME libraries, libhandy uses pkg-config to provide compiler options. The package name is "`libhandy-0.0`".

If you use Automake/Autoconf, in your `configure.ac` script, you might specify something like:

    1
    2
    3

    PKG_CHECK_MODULES(LIBHANDY, [libhandy-0.0])
    AC_SUBST(LIBHANDY_CFLAGS)
    AC_SUBST(LIBHANDY_LIBS)

Or when using the Meson build system you can declare a dependency like:

    1

    dependency('libhandy-0.0')

The "`0.0`" in the package name is the "API version" (indicating "the version of the libhandy API that first appeared in version 0.0") and is essentially just part of the package name.

### Bundling the library

As libhandy uses the Meson build system, bundling it as a subproject when it is not installed is easy. Add this to your `meson.build`:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

    libhandy_dep = dependency('libhandy-0.0', version: '>= 0.0.13')
    if not libhandy_dep.found()
      libhandy = subproject(
        'libhandy',
        install: false,
        default_options: [
          'examples=false',
          'package_subdir=my-project-name',
          'tests=false',
        ]
      )
      libhandy_dep = libhandy.get_variable('libhandy_dep')
    endif

Then add libhandy as a git submodule:

    1

    git submodule add https://source.puri.sm/Librem5/libhandy.git subprojects/libhandy

To bundle the library with your Flatpak application, add the following module to your manifest:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15

    {
      "name" : "libhandy",
      "buildsystem" : "meson",
      "builddir" : true,
      "config-opts": [
        "-Dexamples=false",
        "-Dtests=false"
      ],
      "sources" : [
        {
          "type" : "git",
          "url" : "https://source.puri.sm/Librem5/libhandy.git"
        }
      ]
    }

### Acknowledge the Instability

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, `HANDY_USE_UNSTABLE_API` must be defined for compilation to succeed.

From C code or any compatible language, you can prefix your inclusion of the libhandy header like so:

    1
    2

    #define HANDY_USE_UNSTABLE_API
    #include <handy.h>

Including individual headers rather than `handy.h` is not recommended.

You can also acknoledge this with the definition option of your C compiler, like `-DHANDY_USE_UNSTABLE_API`. This is required from Vala.

To use libhandy from Vala, you must define the acknowledgment in C via `-X -DHANDY_USE_UNSTABLE_API`. If your build system uses a two pass compilation and hence your Vala compiler outputs C (Meson, Automake, or using the `--ccode` Vala compiler option to trigger that) then you must add `-DHANDY_USE_UNSTABLE_API` to your C compiler argments instead.