From a1c3e9bb097b0dabb690972122f53ebc839c558e Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Fri, 13 Jul 2012 12:01:06 +0200 Subject: [PATCH] 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(-) create mode 100644 docs/reference/libsecret/libsecret-using.sgml create mode 100644 docs/reference/libsecret/version-major.xml.in 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 @@ + + 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 @@ + + +]> + +Using libsecret in builds or scripts + + +C: Compiling with libsecret + +Like other GNOME libraries, libsecret uses +pkg-config to provide compiler options. The package +name is "libsecret-&major;". So in your +configure.ac script,you might specify something like: + + +PKG_CHECK_MODULES(LIBSECRET, [libsecret-&major; >= 1.0]) +AC_SUBST(LIBSECRET_CFLAGS) +AC_SUBST(LIBSECRET_LIBS) + + + +Code using libsecret should include the header like this: + + + +#include <libsecret/secret.h> + + + +Including individual headers besides the main header files is not +permitted and will cause an error. + + + +Some parts of the libsecret API are not yet stable. +To use them you need use the libsecret-unstable package. +The API contained in this package will change from time to time. Here's how +you would do it: + + + +PKG_CHECK_MODULES(LIBSECRET, [libsecret-unstable >= 1.0]) +AC_SUBST(LIBSECRET_CFLAGS) +AC_SUBST(LIBSECRET_LIBS) + + + + + +Javascript: Importing libsecret + + +In javascript use the standard introspection import mechanism to get at +libsecret: + + + +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 }); + + + +Some parts of the libsecret API are not yet stable. +It is not recommended that you use these unstable parts +from javascript. Your code will break 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: + + + +// 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); + + + + + +Python: Importing libsecret + + +In python use the standard introspection import mechanism to get at +libsecret: + + + +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 }) + + + +Some parts of the libsecret API are not yet stable. +It is not recommended that you use these unstable parts +from python. Your code will break 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: + + + +# 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); + + + + + +Vala: Compiling with libsecret + + +The package name is "libsecret-&major;". You can use it like +this in your Makefile.am file: + + + +AM_VALAFLAGS = \ + --pkg=libsecret-&major; + + + +Some parts of the libsecret API are not yet stable. +To use them you need use the libsecret-unstable package. +The API contained in this package will change from time to time. Here's how +you would do it: + + + +AM_VALAFLAGS = \ + --pkg=libsecret-unstable + + + + + 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 -- 2.7.4