Compiling with &package_string;

3

Compiling with &package_string;

Notes on compiling

## Using pkg-config

Like other GNOME libraries, &package_string; uses pkg-config to provide compiler options. The package name is "`&package_ver_str;`". So in your `configure.ac` script, you might specify something like:

          PKG_CHECK_MODULES(LIBHANDY, [&package_string;-&package_api_version;])
          AC_SUBST(LIBHANDY_CFLAGS)
          AC_SUBST(LIBHANDY_LIBS)

Or if using Meson/Ninja use a `dependency('&package_string;-&package_api_version;')` dependency.

The "`&package_api_version;`" in the package name is the "API version" (indicating "the version of the &package_string; API that first appeared in version &package_api_version;") and is essentially just part of the package name.

When using the Meson build system you can declare a dependency like

          dependency('libhandy-0.0')

## 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:

          #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 trigger that) then you must add `-DHANDY_USE_UNSTABLE_API` to your C compiler argments instead.