# Libfeedback Overview

## Introduction

The purpose of libfeedback is to make it simple to supply audible, haptic and visual feedback to the user. This is done by notifying a &feedback_daemon; over DBus that a certain event happened and the daemon selects the appropriate feedbacks (such as a buzzing haptic motor or playing an audio file) based on the user session's current feedback profile, feedback theme and available hardware. Events are identified by strings like `message-new-sms` or `message-new-sms`. The available event names are described in the &event_naming_spec;.

&package; provides synchronous and asynchronous APIs to trigger and stop feedback for these events and is usable from other languages than C by GObject introspection.

## Compiling libfeedback applications

### 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(LIBFEEDBACK, [&package_string;-&package_api_version;])
    	AC_SUBST(LIBFEEDBACK_CFLAGS)
    	AC_SUBST(LIBFEEDBACK_LIBS)

### Using Meson/Ninja

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

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

    	#define LIBFEEDBACK_USE_UNSTABLE_API
    	#include <libfeedback.h>

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

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

To use &package_name; from Vala, you must define the acknowledgment in C via `-X -DFEEDBACK_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 `-DLIBFEEDBACK_USE_UNSTABLE_API` to your C compiler arguments instead.