[libsecret] Document how to build with or use libsecret

[Stefan Walter <stefw src gnome org>]

commit a1c3e9bb097b0dabb690972122f53ebc839c558e
Author: Stef Walter <stefw gnome org>
Date:   Fri Jul 13 12:01:06 2012 +0200

    Document how to build with or use libsecret

 .gitignore                                    |    1 +
 configure.ac                                  |    1 +
 docs/reference/libsecret/Makefile.am          |    3 +-
 docs/reference/libsecret/libsecret-docs.sgml  |    2 +
 docs/reference/libsecret/libsecret-using.sgml |  146 +++++++++++++++++++++++++
 docs/reference/libsecret/version-major.xml.in |    1 +
 libsecret/tests/Makefile.am                   |    2 +-
 7 files changed, 154 insertions(+), 2 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index bef9fe7..4cdb0ba 100644
--- a/.gitignore
+++ b/.gitignore
@@ -47,6 +47,7 @@ stamp*
 /build/valgrind-suppressions
 
 /docs/reference/libsecret/version.xml
+/docs/reference/libsecret/version-major.xml
 /docs/reference/libsecret/libsecret-decl-list.txt
 /docs/reference/libsecret/libsecret-decl.txt
 /docs/reference/libsecret/libsecret-scan.c
diff --git a/configure.ac b/configure.ac
index e8b1152..48389f6 100644
--- a/configure.ac
+++ b/configure.ac
@@ -243,6 +243,7 @@ AC_CONFIG_FILES([
 	docs/reference/Makefile
 	docs/reference/libsecret/Makefile
 	docs/reference/libsecret/version.xml
+	docs/reference/libsecret/version-major.xml
 	egg/Makefile
 	egg/tests/Makefile
 	po/Makefile.in
diff --git a/docs/reference/libsecret/Makefile.am b/docs/reference/libsecret/Makefile.am
index 5f05319..1ffa191 100644
--- a/docs/reference/libsecret/Makefile.am
+++ b/docs/reference/libsecret/Makefile.am
@@ -71,6 +71,7 @@ HTML_IMAGES=
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
 content_files = \
 	libsecret-examples.sgml \
+	libsecret-using.sgml \
 	migrating-libgnome-keyring.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
@@ -95,7 +96,7 @@ include $(top_srcdir)/gtk-doc.make
 # e.g. EXTRA_DIST += version.xml.in
 EXTRA_DIST += \
 	version.xml.in \
-	migrating-libgnome-keyring.xml
+	version-major.in
 
 # Files not to distribute
 # for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml
index 428725a..b49a70e 100644
--- a/docs/reference/libsecret/libsecret-docs.sgml
+++ b/docs/reference/libsecret/libsecret-docs.sgml
@@ -33,6 +33,8 @@
 		<xi:include href="xml/secret-paths.xml"/>
 	</part>
 
+	<xi:include href="libsecret-using.sgml"/>
+
 	<xi:include href="xml/migrating-libgnome-keyring.xml"/>
 
 	<xi:include href="xml/annotation-glossary.xml">
diff --git a/docs/reference/libsecret/libsecret-using.sgml b/docs/reference/libsecret/libsecret-using.sgml
new file mode 100644
index 0000000..c531b15
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-using.sgml
@@ -0,0 +1,146 @@
+<?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"; [
+<!ENTITY major SYSTEM "version-major.xml">
+]>
+<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-&major;</literal>". So in your
+<literal>configure.ac</literal> script,you might specify something like:</para>
+
+<informalexample><programlisting>
+PKG_CHECK_MODULES(LIBSECRET, [libsecret-&major; >= 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>
+
+<para>
+Some parts of the <application>libsecret</application> API are not yet stable.
+It is <emphasis>not</emphasis> recommended that you use these unstable parts
+from javascript. Your code <emphasis>will break</emphasis> when the unstable API
+changes, and due to the lack of a compiler you will have no way of knowing when
+it does. If you must use the unstable API, you would do it like this:
+</para>
+
+<informalexample><programlisting language="javascript">
+// Warning: if you use the unstable API from javascript, your're going to have a bad time
+const SecretUnstable = imports.gi.SecretUnstable;
+
+// ... and a here's sample line of code which uses the import
+var collection = SecretUnstable.Collection.for_alias(null, "default", null);
+</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>
+
+<para>
+Some parts of the <application>libsecret</application> API are not yet stable.
+It is <emphasis>not</emphasis> recommended that you use these unstable parts
+from python. Your code <emphasis>will break</emphasis> when the unstable API
+changes, and due to the lack of a compiler you will have no way of knowing when
+it does. If you must use the unstable API, you would do it like this:
+</para>
+
+<informalexample><programlisting language="py">
+# Warning: if you use the unstable API from python, your're going to have a bad time
+from gi.repository import SecretUnstable
+
+# ... and a here's sample line of code which uses the import
+collection = SecretUnstable.Collection.for_alias(None, "default", None);
+</programlisting></informalexample>
+
+</chapter>
+
+<chapter id="using-vala">
+<title>Vala: Compiling with libsecret</title>
+
+<para>
+The package name is "<literal>libsecret-&major;</literal>". You can use it like
+this in your <literal>Makefile.am</literal> file:
+</para>
+
+<informalexample><programlisting>
+AM_VALAFLAGS = \
+	--pkg=libsecret-&major;
+</programlisting></informalexample>
+
+<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>
+AM_VALAFLAGS = \
+	--pkg=libsecret-unstable
+</programlisting></informalexample>
+
+</chapter>
+
+</part>
diff --git a/docs/reference/libsecret/version-major.xml.in b/docs/reference/libsecret/version-major.xml.in
new file mode 100644
index 0000000..e9450db
--- /dev/null
+++ b/docs/reference/libsecret/version-major.xml.in
@@ -0,0 +1 @@
+ SECRET_MAJOR@
\ No newline at end of file
diff --git a/libsecret/tests/Makefile.am b/libsecret/tests/Makefile.am
index 32a16e3..44f5861 100644
--- a/libsecret/tests/Makefile.am
+++ b/libsecret/tests/Makefile.am
@@ -94,7 +94,7 @@ VALA_TESTS_VAPIS = \
 VALA_SRCS = $(VALA_TESTS:=.vala)
 
 .vala.c: $(VALA_TESTS_VAPIS)
-	$(VALA_V)$(VALAC) $(VALA_FLAGS) -C $<
+	$(VALA_V)$(VALAC) $(VALA_FLAGS) $(VALA_TESTS_VAPIS) -C $<
 
 if HAVE_INTROSPECTION
 if ENABLE_VAPIGEN