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-1".

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

1
2
3

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

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

1

dependency('libhandy-1')

The "1" in the package name is the "API version" (indicating "the version of the libhandy API that first appeared in version 1") 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-1', version: '>= 0.80.0')
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 acknowledge 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.

Building on macOS

To build on macOS you need to install the build-dependencies first. This can e.g. be done via brew:

1

brew install pkg-config gtk+3 adwaita-icon-theme meson glade gobject-introspection vala

After running the command above, one may now build the library:

1
2
3
4
5

git clone https://source.puri.sm/Librem5/libhandy.git
cd libhandy
meson . _build
ninja -C _build test
ninja -C _build install

Working with the library on macOS is pretty much the same as on Linux. To link it, use pkg-config:

1

gcc $(pkg-config --cflags --libs gtk+-3.0) $(pkg-config --cflags --libs libhandy-1) main.c -o main