README.md 6.06 KB
Newer Older
Corentin Noël's avatar
Corentin Noël committed
1
2
# Tracker

3
4
5
Tracker is an efficient search engine and
[triplestore](https://en.wikipedia.org/wiki/Triplestore) for desktop, embedded
and mobile.
Corentin Noël's avatar
Corentin Noël committed
6

7
8
The Tracker project is divided into two main repositories:

9
  * [Tracker SPARQL](https://gitlab.gnome.org/GNOME/tracker) contains the
Sam Thursfield's avatar
Sam Thursfield committed
10
11
    triplestore database, provided as the `libtracker-sparql` library
    and implemented using [SQLite](http://sqlite.org/). This repo also contains
12
    the database ontologies and the commandline user interface (`tracker3`).
13
14

  * [Tracker Miners](https://gitlab.gnome.org/GNOME/tracker-miners) contains
15
    the indexer daemon (*tracker-miner-fs-3*) and tools to extract metadata
16
17
    from many different filetypes.

18
More information on Tracker can be found at:
Corentin Noël's avatar
Corentin Noël committed
19

20
  * <https://gnome.pages.gitlab.gnome.org/tracker/>
21
  * <https://wiki.gnome.org/Projects/Tracker>
Corentin Noël's avatar
Corentin Noël committed
22

23
Source code and issue tracking:
Corentin Noël's avatar
Corentin Noël committed
24

25
  * <https://gitlab.gnome.org/GNOME/tracker>
26
  * <https://gitlab.gnome.org/GNOME/tracker-miners>
Corentin Noël's avatar
Corentin Noël committed
27

28
All discussion related to Tracker happens on:
Corentin Noël's avatar
Corentin Noël committed
29

30
  * <https://discourse.gnome.org/tag/tracker>
Corentin Noël's avatar
Corentin Noël committed
31

32
IRC channel #tracker on:
Corentin Noël's avatar
Corentin Noël committed
33

34
  * [irc.gimp.net](irc://irc.gimp.net)
Corentin Noël's avatar
Corentin Noël committed
35

36
37
38
39
40
41
Related projects:

  * [GNOME Online Miners](https://gitlab.gnome.org/GNOME/gnome-online-miners/)
    extends Tracker to allow searching and indexing some kinds of online
    content.

Sam Thursfield's avatar
Sam Thursfield committed
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
## Goals and Non-goals

Here's a summary of the goals and non-goals of the Tracker project.

 1. Provide real-time searching and browsing of desktop content.
 2. Provide searchable data storage for desktop apps.
 3. Allow full-text search within common document types.
 4. Allow advanced queries using a standard query language.
 5. Be secure and private by default.
 6. Be efficient enough for desktop and mobile use.
 7. Be maintainable by a small team.

These are some things we currently don't want to do in Tracker itself.

 * Depend on features of a specific filesystem. Tracker should work on
   all commonly used filesystems.
 * Index source code. There are plenty of IDEs and source-code indexing tools already.
 * Index user data in network / cloud services. This is out of scope for the core of
   Tracker but can be done by third party projects -- see
   [Gnome Online Miners](https://wiki.gnome.org/Projects/GnomeOnlineMiners).
 * Index data on the Web.
 * Provide our own GUI components. Tracker is a middleware component, not an end user
   application.

## Developing Tracker
67
68
69
70
71
72
73
74
75
76
77
78

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.

For the GNOME desktop, consider using the documented [Building a System
Component](https://wiki.gnome.org/Newcomers/BuildSystemComponent) workflow.

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.

Sam Thursfield's avatar
Sam Thursfield committed
79
### Compilation
Corentin Noël's avatar
Corentin Noël committed
80

81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
Tracker uses the [Meson build system](http://mesonbuild.com), which you must
have installed in order to build Tracker.

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.

    git clone https://gitlab.gnome.org/GNOME/tracker.git
    git clone https://gitlab.gnome.org/GNOME/tracker-miners.git

    mkdir tracker-miners/subprojects
    ln -s ../../tracker tracker-miners/subprojects/

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.

97
98
99
100
101
102
> 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.

103
104
105
106
107
    cd tracker-miners
    meson ./build --prefix=$HOME/opt/tracker -Dtracker_core=subproject
    cd build
    ninja install

Sam Thursfield's avatar
Sam Thursfield committed
108
### Running the testsuite
109
110
111
112
113

At this point you can run the Tracker test suite from the `build` directory:

    meson test --print-errorlogs

Sam Thursfield's avatar
Sam Thursfield committed
114
### Using the run-uninstalled script
115
116
117
118
119

Tracker normally runs automatically, indexing content in the background so that
search results are available quickly when needed.

When developing and testing Tracker you will normally want it to run in the
120
121
122
123
foreground instead. You also probably want to run it from a build tree, rather
than installing it somewhere everytime you make a change, and you certainly
should isolates your development version from the real Tracker database in your
home directory.
124

125
126
127
There is a tool to help with this, which is part of the 'trackertestutils'
Python module.  You can run the tool using a helper script generated in the
tracker-miners.git build process named 'run-uninstalled'.
128

129
130
Check the helper script is set up correctly by running this from your
tracker-miners.git build tree:
131

132
    ./run-uninstalled --help
133

134
135
136
If run with no arguments, the script will start an interactive shell. Any
arguments after a `--` sentinel are treated as a command to run in a non-interactive
shell.
137

138
Now check that it runs the correct version of the Tracker CLI:
139

140
    ./run-uninstalled -- tracker3 --version
141

142
143
144
145
Let's try and index some content. (Subtitute ~/Music for any other location
where you have interesting data). We need to explicitly tell the script to wait
for the miners to finish, or it will exit too soon. (This is a workaround for
[issue #122](https://gitlab.gnome.org/GNOME/tracker/issues/122).)
146

147
    ./run-uninstalled --wait-for-miner=Files --wait-for-miner=Extract -- tracker3 index --add ~/Music
148

149
Let's see what files were found!
150

151
    ./run-uninstalled  -- tracker3 sparql --dbus-service=org.freedesktop.Tracker3.Miner.Files -q 'SELECT ?url { ?u nie:url ?url }'
152

153
Or, you can try a full-text search ...
Corentin Noël's avatar
Corentin Noël committed
154

155
    ./run-uninstalled -- tracker3 search "bananas"
Corentin Noël's avatar
Corentin Noël committed
156

157
There are many more things you can do with the script.
Corentin Noël's avatar
Corentin Noël committed
158

159
For more information about developing Tracker, look at
Sam Thursfield's avatar
Sam Thursfield committed
160
https://wiki.gnome.org/Projects/Tracker and HACKING.md.