<?xml version='1.0' encoding="ISO-8859-1"?>

<part id="tracker-overview">
  <title>Overview</title>
  <partintro>
    <para>
      The libtracker-sparql library is the foundation for Tracker
      querying and inserting into the data store. The data store
      allows both querying and inserting using SPARQL based on the
      Nepomuk ontology.
    </para>
  </partintro>


  <chapter id="tracker-overview-connection-methods">
    <title>Connection methods</title>

    <para>
      The Tracker SPARQL library provides several underlying methods to perform
      queries and updates to the Tracker Store.

      <itemizedlist>
	<listitem>
	  <emphasis>Direct Access:</emphasis>
	  <para>
	    All Read-Only operations done in a
	    <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
	    will by default use this method, as it doesn't involve any D-Bus traffic,
	    and thus, it will perform much better. There is no real connection with
	    the Tracker Store in this case, as the access is direct to the underlying
	    SQLite database. Again, note that this method applies only to
	    <emphasis>Read-Only</emphasis> operations.
	  </para>
	  <para>
	    If you plan to only do Read-Only queries to the store, you can get the
	    <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
	    object using <function><link linkend="tracker-sparql-connection-get-direct">tracker_sparql_connection_get_direct</link></function>. Otherwise, if you also plan to use the same connection object
	    for <emphasis>Write</emphasis> operations, you must get the connection object with
	    <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
	  </para>
	</listitem>
	<listitem>
	  <emphasis>D-Bus FD passing:</emphasis>
	  <para>
	    The <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
	    will use the File Descriptor passing method via D-Bus to connect to the Store for all non
		Read-Only queries on
	    <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
	    objects obtained with
	    <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
	  </para>
      <para>
		See the <link linkend="tracker-overview-environment-variables">Environment Variables</link> section
		to check how you can force also Read-Only queries to be done using D-Bus.
      </para>
	</listitem>
      </itemizedlist>
    </para>
  </chapter>

  <chapter id="tracker-overview-compiling">
    <title>Compiling applications</title>

    <para>
      To compile applications using libtracker-sparql, you
      need to tell the compiler where to find the proper header files
      and libraries. This is done with the
      <application>pkg-config</application> utility.
    </para>

    <para>
      The following interactive shell session demonstrates how
      <application>pkg-config</application> is used (the actual output on
      your system may be different):
<programlisting>
$ pkg-config --cflags tracker-sparql-0.12
-pthread -I/usr/include/tracker-0.12 -I/usr/include/tracker-0.12/libtracker-sparql -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include

$ pkg-config --libs tracker-sparql-0.12
-Wl,--export-dynamic -pthread -ltracker-sparql-0.12 -lgio-2.0 -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
</programlisting>
    </para>
    <para>
      The simplest way to compile a program is to use the "backticks"
      feature of the shell. If you enclose a command in backticks
      (<emphasis>not single quotes</emphasis>), then its output will be
      substituted into the command line before execution:
<programlisting>
 $ cc `pkg-config --cflags --libs tracker-sparql-0.12` hello.c -o hello
</programlisting>
    </para>

  </chapter>

  <chapter id="tracker-overview-environment-variables">
    <title>Environment Variables</title>

    <para>
      There are a number of environment variables which affect the way
      that the libtracker-sparql library will do its work. Those
      environment variables are described here.

      <itemizedlist>
	<listitem>
	  <emphasis>TRACKER_USE_LOG_FILES</emphasis>
	  <para>
	    Don't just log to stdout and stderr, but to log files too
	    which are kept in $HOME/.local/share/tracker/. This came
	    into effect in 0.15.3 and 0.16.0. After this version of
	    Tracker, logging to file (usually useful for debugging)
	    can only be done by declaring this environment variable.
	  </para>
	</listitem>
	<listitem>
	  <emphasis>TRACKER_USE_CONFIG_FILES</emphasis>
	  <para>
	    Don't use GSettings, instead use a config file similar to
	    how settings were saved in 0.10.x. That is, a file which
	    is much like an .ini file. These are saved to
	    $HOME/.config/tracker/
	  </para>
	</listitem>
	<listitem>
	  <emphasis>TRACKER_SPARQL_BACKEND</emphasis>
	  <para>
	    Backends for libtracker-sparql are dynamically loaded at
	    run time. Currently there are only two backends which are
	    <link linkend="overview-tracker-connection-methods">explained
	    more closely</link> in the previous chapter. In short,
	    this environment variable gives the client the ability to
	    directly mandate which backend they want to use. The
	    value can be set to either "direct" or "bus". A "direct"
	    value means the direct access approach will be forced. A
	    "bus" value means a D-Bus / IPC approach will be forced.
	  </para>
	</listitem>
	<listitem>
	  <emphasis>TRACKER_SPARQL_CACHE_SIZE</emphasis>
	  <para>
	    Tracker caches database statements which occur frequently to make
	    subsequent repeat queries much faster. The cache size is
	    set to <emphasis>100</emphasis> by default for each type
	    (select and update queries). This must be at
	    least <emphasis>2</emphasis> as a minimum, any less and a
	    value of <emphasis>3</emphasis> is used instead. The
	    number represents the number of cached statements to keep
	    around. This environment variable is used mainly for
	    testing purposes.
	  </para>
	  <para>
	    Tracker's store also has environment variables to control
	    this behavior, see the manual pages
	    for <emphasis>tracker-store</emphasis>
	    regarding <emphasis>TRACKER_STORE_SELECT_CACHE_SIZE</emphasis>
	    and <emphasis>TRACKER_STORE_UPDATE_CACHE_SIZE</emphasis>.
	  </para>
	</listitem>
	<listitem>
	  <emphasis>TRACKER_VERBOSITY</emphasis>
	  <para>
	    Historically, all queries would go
	    through <emphasis>tracker-store</emphasis> and all
	    requests would be logged according to the verbosity set
	    in <emphasis>tracker-store.cfg</emphasis> (see manual
	    pages for <emphasis>tracker-store.cfg</emphasis>). Since
	    libtracker-sparql may
	    circumvent <emphasis>tracker-store</emphasis> if using the
	    direct access backend, this environment variable was added
	    to let clients choose the log level. The same values apply
	    to all other processes which have logging and a
	    configuration to control it. Values range
	    from <emphasis>0</emphasis> to <emphasis>3</emphasis>,
	    0=errors, 1=minimal, 2=detailed, 3=debug. By default it
	    is <emphasis>0</emphasis>.
	  </para>
	</listitem>
      </itemizedlist>
    </para>

  </chapter>

</part>

