diff options
author | Sam Thursfield <sam@afuera.me.uk> | 2020-10-13 13:51:09 +0200 |
---|---|---|
committer | Sam Thursfield <sam@afuera.me.uk> | 2020-10-13 13:51:42 +0200 |
commit | c32f172f1b48f6cfe9845ca233f643bde81abd0c (patch) | |
tree | 282279dd82d92a333c821806c34b1cacff031fc7 | |
parent | 782ceecbda91ae15ae8191e3e933099357c9d3a6 (diff) | |
download | tracker-sam/docs-flatpak.tar.gz |
docs: Add information related to Flatpaksam/docs-flatpak
Also some general cleanups, in particular removing domain-ontology
feature which now belongs in tracker-miners.git, and can be
documented there with an example app.
See: https://gitlab.gnome.org/GNOME/tracker/-/issues/236
-rw-r--r-- | docs/reference/libtracker-sparql/libtracker-sparql-docs.xml | 1 | ||||
-rw-r--r-- | docs/reference/libtracker-sparql/overview.xml | 60 | ||||
-rw-r--r-- | docs/reference/libtracker-sparql/private-store.xml | 113 |
3 files changed, 53 insertions, 121 deletions
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml b/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml index 4b5793f77..792f309e7 100644 --- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml +++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml @@ -50,7 +50,6 @@ </part> <xi:include href="ontologies.xml"/> - <xi:include href="private-store.xml"/> <xi:include href="examples.xml"/> <xi:include href="limits.xml"/> <xi:include href="performance.xml"/> diff --git a/docs/reference/libtracker-sparql/overview.xml b/docs/reference/libtracker-sparql/overview.xml index 0e746e1a1..49587360f 100644 --- a/docs/reference/libtracker-sparql/overview.xml +++ b/docs/reference/libtracker-sparql/overview.xml @@ -4,13 +4,17 @@ <title>Overview</title> <partintro> <para> - The libtracker-sparql library allows creating and connecting to - one or more "triplestore" databases. + Tracker SPARQL allows creating and connecting to one or more triplestore databases. + It is used by the + <ulink role="online-location" url="https://gitlab.gnome.org/GNOME/tracker-miners/"> + Tracker Miners filesystem indexer + </ulink>, and can also store and publish any kind of app data. </para> <para> - Data queries and updates are done using the SPARQL graph query - language. The <type><link linkend="TrackerResource">TrackerResource</link></type> - API provides helpers for updating data. + Querying data is done using the SPARQL graph query language. See the + <link linkend="Examples">Examples</link> to find out how this works. + Storing data can also be done using SPARQL, or using the + <type><link linkend="TrackerResource">TrackerResource</link></type> API. </para> <para> You can share a database over D-Bus using the @@ -20,24 +24,66 @@ query, or by connecting directly with <function><link linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>. </para> + <para> + Tracker SPARQL partitions the database into multiple graphs. + You can implementing access control restrictions based on + graphs, and we provide a Flatpak portal that does so. + The number of graphs is <link linkend="limits">limited</link>. + </para> </partintro> - <chapter id="tracker-overview-connection-methods"> <title>Connection methods</title> <para> You can create and access a private store using <function><link linkend="tracker-sparql-connection-new">tracker_sparql_connection_new</link></function>. + This is useful to store app-specific data. </para> <para> To connect to another database on the same local machine, such as the - one exposed by the Tracker filesystem miner, use + one exposed by Tracker Miner FS, use <function><link linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>. </para> <para> To connect to another a database on a remote machine, use <function><link linkend="tracker-sparql-connection-remote-new">tracker_sparql_connection_remote_new</link></function>. + This can be used to query online databases that provide a SPARQL + endpoint, such as + <ulink role="online-location" url="https://wiki.dbpedia.org/about">DBpedia</ulink> + . + </para> + </chapter> + + <chapter id="tracker-overview-flatpak"> + <title>Connecting from Flatpak</title> + + <para> + Tracker SPARQL provides a portal for the + <ulink role="online-location" url="https://flatpak.org/">Flatpak</ulink> + application sandboxing system. This lets + you control which parts of a database each app can query. + </para> + <para> + The app's Flatpak manifest needs to specify which graph(s) the app will + access. See the <ulink role="online-location" url="https://gitlab.gnome.org/GNOME/tracker/-/blob/master/examples/flatpak/org.example.TrackerSandbox.json">example app</ulink> + and the <ulink role="online-location" url="https://gnome.pages.gitlab.gnome.org/tracker/docs/commandline/#tracker-xdg-portal-3">portal documentation</ulink> + to see how. + No code changes are needed in the app, as + <function><link linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>. + will automatically try connect via the portal + if it can't talk to the given D-Bus name directly. + </para> + <para> + Tracker SPARQL is included in the <ulink role="online-location" url="https://docs.flatpak.org/en/latest/available-runtimes.html#gnome">GNOME Flatpak SDK and runtime</ulink>. + If the app uses a different runtime, you may need to build Tracker SPARQL in the app manifest. + </para> + <para> + The app might use the Tracker Miner FS search index. Ideally this is done via the portal, + using the search index maintained on the host. Since not all OSes ship tracker-miner-fs-3, + we recommend that apps bundle it inside the Flatpak and connect to the bundled version as + a fallback. See <ulink role="online-location" url="https://gitlab.gnome.org/GNOME/gnome-music/">GNOME Music</ulink> + for an example of how to do this. </para> </chapter> </part> diff --git a/docs/reference/libtracker-sparql/private-store.xml b/docs/reference/libtracker-sparql/private-store.xml deleted file mode 100644 index c598173ac..000000000 --- a/docs/reference/libtracker-sparql/private-store.xml +++ /dev/null @@ -1,113 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> - -<part id="tracker-private-store" xmlns:xi="http://www.w3.org/2003/XInclude"> - <title>Isolating tracker-store clients</title> - <partintro> - <para> - Every user of tracker_sparql_connection_get() or tracker_sparql_connection_get_async() - relies on an external tracker-store instance to maintain the database, and possibly - on additional tracker miners to write the data consumed by the application. - </para> - <para> - Traditionally there has been only a single instance of tracker-store and miners, - shared by all consumers of Tracker data. With Tracker 2.0 it became possible to let - clients spawn their own sets of these services. - </para> - </partintro> - - <chapter id="private-daemons"> - <title>Defining a private domain ontology</title> - <para> - In order to make Tracker aware of this private setup, a domain ontology rule - must be dropped by the application on $(datadir)/tracker/domain-ontologies/, - the file name will be usually the DBus name or application ID of the client - prepended by ".rule", eg. org.example.App.rule - </para> - <para> - The following example would allow org.example.App to set up a private set - of services to index the filesystem. - </para> - <programlisting> -[DomainOntology] -# All locations accept -# 1) Paths relative from a variable, the variables -# may be: HOME, XDG_CACHE_HOME, XDG_DATA_HOME, XDG_RUNTIME_DIR, -# XDG_DESKTOP_DIR, XDG_DOCUMENTS_DIR, XDG_DOWNLOAD_DIR, -# XDG_MUSIC_DIR, XDG_PICTURES_DIR, XDG_PUBLICSHARE_DIR, -# XDG_VIDEOS_DIR. -# -# eg. $XDG_CACHE_HOME/... -# -# 2) URIs -# -# eg. file:///var/... -# - -# Location for the Tracker database (not optional) -CacheLocation=$XDG_CACHE_HOME/example-app - -# Location for the data journal, used in data recovery -# situations (optional) -JournalLocation=$XDG_DATA_HOME/example-app/journal - -# Name of the ontology to use, must be one located in -# $(sharedir)/tracker/ontologies -OntologyName=nepomuk - -# DBus name for the owner (not optional). Tracker will use -# the domain as the prefix of the DBus name for all the -# services related to this domain ontology. -# -# eg. org.gnome.Photos -Domain=org.example.App - -# Miners that the domain ontology will require. This is -# purely a hint (mainly for libtracker-control), and not -# any sort of white list. Anything else knowing about this -# domain ontology may still perform updates, miners and -# non-miners. -Miners=Miner.Files;Miner.Extract; - </programlisting> - <para> - The client could then instruct Tracker libraries to use - this private set up through the following call: - </para> - <programlisting> -tracker_sparql_connection_set_domain ("org.example.App"); - </programlisting> - <para> - It is also possible to pass a full path to the domain rule. If the first - character of the domain name is / it will be treated as a full path. - </para> - </chapter> - <chapter id="recommendations"> - <title>Additional precautions and recommendations</title> - <para> - In order to work flawlessly with the created services, the - client must adopt some precautions that were optional in the - past, but now have become mandatory. - </para> - <formalpara> - <title>Use TrackerNotifier to receive notifications</title> - <para> - Listening directly to the GraphUpdated DBus signal will yield - the wrong results, since it relies on the DBus name adopted by - the default tracker-store service. - </para> - </formalpara> - <formalpara> - <title>Use TrackerMinerManager to ensure services are started</title> - <para> - The miner lifetime has been traditionally unclear, being those - usually deemed a system service that would usually be there. - When using private services that assumption can't hold true, - so the client is responsible for ensuring those services are - started. - </para> - <para> - Note that this is the recommended behavior anyway even if the - client were not to use private services. - </para> - </formalpara> - </chapter> -</part> |