Merge branch 'sam/2.2.3-readme-updates' into tracker-2.2

See merge request GNOME/tracker!92

1 files changed, 84 insertions, 142 deletions

diff --git a/README.md b/README.md
index ebbd2b0db..48c374e6f 100644
--- a/README.md
+++ b/README.md
@@ -1,189 +1,131 @@
 # Tracker
 
-Tracker is a search engine and that allows the user to find their
-data as fast as possible. Users can search for their files and
-search for content in their files too.  
+Tracker is an efficient search engine and
+[triplestore](https://en.wikipedia.org/wiki/Triplestore) for desktop, embedded
+and mobile.
 
-Tracker is a semantic data storage for desktop and mobile devices.
-Tracker uses W3C standards for RDF ontologies using Nepomuk with
-SPARQL to query and update the data.
+The Tracker project is divided into two main repositories:
 
-Tracker is a central repository of user information, that provides
-two big benefits for the desktop; shared data between applications
-and information which is relational to other information (for
-example: mixing contacts with files, locations, activities and
-etc.).
+  * [Tracker core](https://gitlab.gnome.org/GNOME/tracker) contains the database
+    (*tracker-store*), the database ontologies, the commandline user
+    interface (`tracker`), and several support libraries.
 
-This central repository works with a well defined data model that
-applications can rely on to store and recover their information.
-That data model is defined using a semantic web artifact called
-ontology. An ontology defines the relationships between the
-information stored in the repository.
+  * [Tracker Miners](https://gitlab.gnome.org/GNOME/tracker-miners) contains
+    the indexer daemon (*tracker-miner-fs*) and tools to extract metadata
+    from many different filetypes.
 
-An EU-funded project called Nepomuk was started to define some of
-the core ontologies to be modeled on the Desktop. Tracker uses this
-to define the data's relationships in a database.
+More information on Tracker can be found at:
 
-All discussion related to tracker happens on the Tracker
-mailing list
+  * <https://wiki.gnome.org/Projects/Tracker>
 
-        https://mail.gnome.org/mailman/listinfo/tracker-list
+Source code and issue tracking:
 
-IRC channel #tracker on:
-
-        irc.gimp.net
-
-Bugs and feature requests should be filed at:
-
-        https://gitlab.gnome.org/GNOME/tracker/issues
-
-More infomation on Tracker can be found at:
-
-        https://wiki.gnome.org/Projects/Tracker
-
-Repository can be found at:
-
-        https://gitlab.gnome.org/GNOME/tracker
-
-The official RoadMap (aka TODO) can be found at:
-
-        https://wiki.gnome.org/Projects/Tracker/Roadmap
-
-
-## Use Cases
-
-Tracker is the most powerful open source metadata database and
-indexer framework currently available and because it is built
-around a combination indexer and SQL database and not a
-dedicated indexer, it has much more powerful use cases:
-
-  * Provide search and indexing facilities similar to those on
-  other systems (Windows Vista and Mac OS X).
+  * <https://gitlab.gnome.org/GNOME/tracker>
 
-  * Common database storage for all first class objects (e.g. a
-  common music/photo/contacts/email/bookmarks/history database)
-  complete with additional metadata and tags/keywords.
+All discussion related to Tracker happens on:
 
-  * Comprehensive one stop solution for all applications needing
-  an object database, powerful search (via RDF Query), first class
-  methods, related metadata and user-definable metadata/tags.
+  * <https://mail.gnome.org/mailman/listinfo/tracker-list>
 
-  * Can provide a full semantic desktop with metadata everywhere.
-
-  * Can provide powerful criteria-based searching suitable for
-  creating smart file dialogs and vfolder systems.
-
-  * Can provide a more intelligent desktop using statistical
-  metadata.
-
-## Features
-
-  * Desktop-neutral design (it's a freedesktop product built
-  around other freedesktop technologies like D-Bus and XDGMime
-  but contains no GNOME-specific dependencies besides GLib).
-
-  * Very memory efficient. Unlike some other indexers, Tracker is
-  designed and built to run well on mobile and desktop systems with
-  lower memory (256MB or less).
-
-  * Non-bloated and written in C for maximum efficiency.
-
-  * Small size and minimal dependencies makes it easy to bundle
-  into various distros, including live CDs.
-
-  * Provides option to disable indexing when running on battery.
-
-  * Provides option to index removable devices.
-
-  * Implements the freedesktop specification for metadata
-  (https://freedesktop.org/wiki/Standards/shared-filemetadata-spec/).
-
-  * Extracts embedded File, Image, Document and Audio type
-  metadata from files.
+IRC channel #tracker on:
 
-  * Supports the WC3's RDF Query syntax for querying metadata.
+  * [irc.gimp.net](irc://irc.gimp.net)
 
-  * Provides support for both free text search (like Beagle/Google)
-  as well as structured searches using RDF Query.
+Related projects:
 
-  * Responds in real time to file system changes to keep its
-  metadata database up to date and in sync.
+  * [GNOME Online Miners](https://gitlab.gnome.org/GNOME/gnome-online-miners/)
+    extends Tracker to allow searching and indexing some kinds of online
+    content.
 
-  * Fully extensible with custom metadata - you can store,
-  retrieve, register and search via RDF Query all your own custom
-  metadata.
+# Developing Tracker
 
-  * Can extract a file's contents as plain text and index them.
+If you want to help develop and improve Tracker, great! Remember that Tracker
+is a middleware component, designed to be integrated into larger codebases. To
+fully test a change you may need to build and test Tracker as part of another
+project.
 
-  * Can provide thumbnailing on the fly.
+For the GNOME desktop, consider using the documented [Building a System
+Component](https://wiki.gnome.org/Newcomers/BuildSystemComponent) workflow.
 
-  * It auto-pauses indexing when running low on diskspace.
+It's also possible to build Tracker on its own and install it inside your home
+directory for testing purposes.  Read on for instructions on how to do this.
 
 ## Compilation
 
-To setup the project for compilation after checking it out from
-the git repository, use:
-
-        meson build --prefix=/usr --sysconfdir=/etc
+Tracker uses the [Meson build system](http://mesonbuild.com), which you must
+have installed in order to build Tracker.
 
-To start compiling the project use:
+We recommend that you build tracker core as a subproject of tracker-miners.
+You can do this by cloning both repos, then creating a symlink in the
+`subprojects/` directory of tracker-miners.git to the tracker.git checkout.
 
-        ninja -C build
-        ninja install
+    git clone https://gitlab.gnome.org/GNOME/tracker.git
+    git clone https://gitlab.gnome.org/GNOME/tracker-miners.git
 
-If you install using any other prefix, you might have problems
-with files not being installed correctly. (You may need to copy
-and amend the dbus service file to the correct directory and/or
-might need to update ld_conf if you install into non-standard
-directories.)
+    mkdir tracker-miners/subprojects
+    ln -s ../../tracker tracker-miners/subprojects/
 
-## Running Tracker
+Now you can run the commands below to build Tracker and install it in a
+new, isolated prefix named `opt/tracker` inside your home folder.
 
-### Usage
+> NOTE: If you see 'dependency not found' errors from Meson, that means there
+> is a package missing on your computer that you need to install so you can
+> compile Tracker. On Ubuntu/Debian, you can run `apt build-dep tracker-miners`
+> and on Fedora `dnf build-dep tracker-miners` to install all the necessary
+> packages.
 
-Tracker normally starts itself when users log in. You can indexing by running:
+    cd tracker-miners
+    meson ./build --prefix=$HOME/opt/tracker -Dtracker_core=subproject
+    cd build
+    ninja install
 
-    $prefix/libexec/tracker-miner-fs
+## Running the testsuite
 
-You can configure how this works using:
+At this point you can run the Tracker test suite from the `build` directory:
 
-    $prefix/bin/tracker-preferences
+    meson test --print-errorlogs
 
-You can monitor data miners using:
+## Developing with tracker-sandbox
 
-    $prefix/bin/tracker-status-icon
+Tracker normally runs automatically, indexing content in the background so that
+search results are available quickly when needed.
 
-You can do simple searching using an applet:
+When developing and testing Tracker you will normally want it to run in the
+foreground instead. The `tracker-sandbox` tool exists to help with this.
 
-    $prefix/libexec/tracker-search-bar
+You can run the tool directly from the tracker.git source tree. Ensure you are
+in the top of the tracker source tree and type this to see the --help output: 
 
-You can do more extensive searching using:
+    ./utils/sandbox/tracker-sandbox.py --help
 
-    $prefix/bin/tracker-search-tool
+You should always pass the `--prefix` option, which should be the same as the
+--prefix argument you passed to Meson. You also need to use `--index` which
+controls where internal state files like the database are kept. You may also
+want to pass `--debug` to see detailed log output.
 
-### Setting Inotify Watch Limit
+Now you can index some files using `--update` mode. Here's how to index files
+in `~/Documents` for example:
 
-When watching large numbers of folders, its possible to exceed
-the default number of inotify watches. In order to get real time
-updates when this value is exceeded it is necessary to increase
-the number of allowed watches. This can be done as follows:
+    ./utils/sandbox/tracker-sandbox.py  --prefix ~/opt/tracker --index ~/tracker-content \
+        --update --content ~/Documents
 
-  1. Add this line to /etc/sysctl.conf:
-     "fs.inotify.max_user_watches = (number of folders to be
-      watched; default used to be 8192 and now is 524288)"
+You can then list the files that have been indexed...
 
-  2. Reboot the system OR (on a Debian-like system) run
-     "sudo /etc/init.d/procps restart"
+    ./utils/sandbox/tracker-sandbox.py  --prefix ~/opt/tracker --index ~/tracker-content \
+        --list-files
 
-## Further Help
+... run a full-text search ...
 
-### Man pages
+    ./utils/sandbox/tracker-sandbox.py  --prefix ~/opt/tracker --index ~/tracker-content \
+        --search "bananas"
 
-Every config file and every binary has a man page. If you start with
-tracker-store, you should be able to find out about most other
-commands on the SEE ALSO section.
+... or run a SPARQL query on the content:
 
-### Utilities
+    ./utils/sandbox/tracker-sandbox.py  --prefix ~/opt/tracker --index ~/tracker-content \
+        --sparql "SELECT ?url { ?resource a nfo:FileDataObject ; nie:url ?url . }"
 
-There are a range of tracker utilities that help you query for data.
+You can also open a shell inside the sandbox environment. From here you can run
+the `tracker` commandline tool, and you can run the Tracker daemons manually
+under a debugger such as GDB.
 
+For more information about developing Tracker, look at
+https://wiki.gnome.org/Projects/Tracker.