<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<part id="using">
<title>Using libsecret in builds or scripts</title>

<chapter id="using-c">
<title>C: Compiling with libsecret</title>

<para>Like other GNOME libraries, <application>libsecret</application> uses
<application>pkg-config</application> to provide compiler options. The package
name is "<literal>libsecret-1</literal>". So in your
<literal>configure.ac</literal> script,you might specify something like:</para>

<informalexample><programlisting>
PKG_CHECK_MODULES(LIBSECRET, [libsecret-1 >= 1.0])
AC_SUBST(LIBSECRET_CFLAGS)
AC_SUBST(LIBSECRET_LIBS)
</programlisting></informalexample>

<para>
Code using <application>libsecret</application> should include the header like this:
</para>

<informalexample><programlisting>
#include &lt;libsecret/secret.h&gt;
</programlisting></informalexample>

<para>
Including individual headers besides the main header files is not
permitted and will cause an error.
</para>

<para>
Some parts of the <application>libsecret</application> API are not yet stable.
To use them you need use the <literal>libsecret-unstable</literal> package.
The API contained in this package will change from time to time. Here's how
you would do it:
</para>

<informalexample><programlisting>
PKG_CHECK_MODULES(LIBSECRET, [libsecret-unstable >= 1.0])
AC_SUBST(LIBSECRET_CFLAGS)
AC_SUBST(LIBSECRET_LIBS)
</programlisting></informalexample>

</chapter>

<chapter id="using-js">
<title>Javascript: Importing libsecret</title>

<para>
In javascript use the standard introspection import mechanism to get at
<application>libsecret</application>:
</para>

<informalexample><programlisting language="javascript">
const Secret = imports.gi.Secret;

// ... and here's a sample line of code which uses the import
var schema = new Secret.Schema.new("org.mock.Schema",
	Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING });
</programlisting></informalexample>

</chapter>

<chapter id="using-python">
<title>Python: Importing libsecret</title>

<para>
In python use the standard introspection import mechanism to get at
<application>libsecret</application>:
</para>

<informalexample><programlisting language="py">
from gi.repository import Secret

# ... and a here's sample line of code which uses the import
schema = Secret.Schema.new("org.mock.Schema",
	Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING })
</programlisting></informalexample>

</chapter>

<chapter id="using-vala">
<title>Vala: Compiling with libsecret</title>

<para>
The package name is "<literal>libsecret-1</literal>". You can use it like
this in your <literal>Makefile.am</literal> file:
</para>

<informalexample><programlisting>
AM_VALAFLAGS = \
	--pkg=libsecret-1
</programlisting></informalexample>

<para>
Some parts of the <application>libsecret</application> API are not yet stable.
To use them you need to define the SECRET_WITH_UNSTABLE C preprocessor
macro to use them, or else the build will fail:
</para>

<informalexample><programlisting>
AM_CPPFLAGS = \
	-DSECRET_WITH_UNSTABLE=1
</programlisting></informalexample>

</chapter>

</part>
