docs/reference/libsecret/libsecret-using.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 <!ENTITY major SYSTEM "version-major.xml">
   5 ]>
   6 <part id="using">
   7 <title>Using libsecret in builds or scripts</title>
   8
   9 <chapter id="using-c">
  10 <title>C: Compiling with libsecret</title>
  11
  12 <para>Like other GNOME libraries, <application>libsecret</application> uses
  13 <application>pkg-config</application> to provide compiler options. The package
  14 name is "<literal>libsecret-&major;</literal>". So in your
  15 <literal>configure.ac</literal> script,you might specify something like:</para>
  16
  17 <informalexample><programlisting>
  18 PKG_CHECK_MODULES(LIBSECRET, [libsecret-&major; >= 1.0])
  19 AC_SUBST(LIBSECRET_CFLAGS)
  20 AC_SUBST(LIBSECRET_LIBS)
  21 </programlisting></informalexample>
  22
  23 <para>
  24 Code using <application>libsecret</application> should include the header like this:
  25 </para>
  26
  27 <informalexample><programlisting>
  28 #include &lt;libsecret/secret.h&gt;
  29 </programlisting></informalexample>
  30
  31 <para>
  32 Including individual headers besides the main header files is not
  33 permitted and will cause an error.
  34 </para>
  35
  36 <para>
  37 Some parts of the <application>libsecret</application> API are not yet stable.
  38 To use them you need use the <literal>libsecret-unstable</literal> package.
  39 The API contained in this package will change from time to time. Here's how
  40 you would do it:
  41 </para>
  42
  43 <informalexample><programlisting>
  44 PKG_CHECK_MODULES(LIBSECRET, [libsecret-unstable >= 1.0])
  45 AC_SUBST(LIBSECRET_CFLAGS)
  46 AC_SUBST(LIBSECRET_LIBS)
  47 </programlisting></informalexample>
  48
  49 </chapter>
  50
  51 <chapter id="using-js">
  52 <title>Javascript: Importing libsecret</title>
  53
  54 <para>
  55 In javascript use the standard introspection import mechanism to get at
  56 <application>libsecret</application>:
  57 </para>
  58
  59 <informalexample><programlisting language="javascript">
  60 const Secret = imports.gi.Secret;
  61
  62 // ... and here's a sample line of code which uses the import
  63 var schema = new Secret.Schema.new("org.mock.Schema",
  64         Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING });
  65 </programlisting></informalexample>
  66
  67 <para>
  68 Some parts of the <application>libsecret</application> API are not yet stable.
  69 It is <emphasis>not</emphasis> recommended that you use these unstable parts
  70 from javascript. Your code <emphasis>will break</emphasis> when the unstable API
  71 changes, and due to the lack of a compiler you will have no way of knowing when
  72 it does. If you must use the unstable API, you would do it like this:
  73 </para>
  74
  75 <informalexample><programlisting language="javascript">
  76 // Warning: if you use the unstable API from javascript, your're going to have a bad time
  77 const SecretUnstable = imports.gi.SecretUnstable;
  78
  79 // ... and a here's sample line of code which uses the import
  80 var collection = SecretUnstable.Collection.for_alias(null, "default", null);
  81 </programlisting></informalexample>
  82
  83 </chapter>
  84
  85 <chapter id="using-python">
  86 <title>Python: Importing libsecret</title>
  87
  88 <para>
  89 In python use the standard introspection import mechanism to get at
  90 <application>libsecret</application>:
  91 </para>
  92
  93 <informalexample><programlisting language="py">
  94 from gi.repository import Secret
  95
  96 # ... and a here's sample line of code which uses the import
  97 schema = Secret.Schema.new("org.mock.Schema",
  98         Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING })
  99 </programlisting></informalexample>
 100
 101 <para>
 102 Some parts of the <application>libsecret</application> API are not yet stable.
 103 It is <emphasis>not</emphasis> recommended that you use these unstable parts
 104 from python. Your code <emphasis>will break</emphasis> when the unstable API
 105 changes, and due to the lack of a compiler you will have no way of knowing when
 106 it does. If you must use the unstable API, you would do it like this:
 107 </para>
 108
 109 <informalexample><programlisting language="py">
 110 # Warning: if you use the unstable API from python, your're going to have a bad time
 111 from gi.repository import SecretUnstable
 112
 113 # ... and a here's sample line of code which uses the import
 114 collection = SecretUnstable.Collection.for_alias(None, "default", None);
 115 </programlisting></informalexample>
 116
 117 </chapter>
 118
 119 <chapter id="using-vala">
 120 <title>Vala: Compiling with libsecret</title>
 121
 122 <para>
 123 The package name is "<literal>libsecret-&major;</literal>". You can use it like
 124 this in your <literal>Makefile.am</literal> file:
 125 </para>
 126
 127 <informalexample><programlisting>
 128 AM_VALAFLAGS = \
 129         --pkg=libsecret-&major;
 130 </programlisting></informalexample>
 131
 132 <para>
 133 Some parts of the <application>libsecret</application> API are not yet stable.
 134 To use them you need use the <literal>libsecret-unstable</literal> package.
 135 The API contained in this package will change from time to time. Here's how
 136 you would do it:
 137 </para>
 138
 139 <informalexample><programlisting>
 140 AM_VALAFLAGS = \
 141         --pkg=libsecret-unstable
 142 </programlisting></informalexample>
 143
 144 </chapter>
 145
 146 </part>