Instructions to run on startup in OS X (fixes #3)
[darcs-mirror-arbtt.git] / arbtt.html
1 <!DOCTYPE html>
2 <html lang="en">
3 <head>
4     <meta charset="utf-8">
5     <title>arbtt: the automatic, rule-based time tracker</title>
6     <link rel="stylesheet" href="arbtt.css">
7 </head>
8
9 <body>
10     <div id="wrapper">
11         <nav>
12             <h1 class="title">arbtt</h1>
13             <p class="title"><b>a</b>utomatic, <b>r</b>ule-<b>b</b>ased <b>t</b>ime <b>t</b>racker</p>
14             <ul>
15                 <li><a href="#what">What is it?</a></li>
16                 <li><a href="#how">How does it work?</a></li>
17                 <li><a href="#install">Installation</a></li>
18                 <li><a href="doc/users_guide/index.html">→ Documentation</a></li>
19                 <li><a href="https://bitbucket.org/nomeata/arbtt/issues">→ Bugs and issues</a></li>
20                 <li><a href="#contact">Get in touch</a></li>
21             </ul>
22         </nav>
23         <div id="content">
24             <section id="what">
25                 <h2>What is arbtt?</h2>
26                 <p><b>arbtt</b> is a cross-platform, completely automatic time tracker.</p>
27                 <p>There are lots of time-tracking programs out there that allow you to
28                 collect statistics about how you spend your time,
29                 which activities are your biggest time-wasters, and so on.
30                 However, most of them require explicit action on your part:
31                 you have to manually enter what activity or project you're working on,
32                 and that has several disadvantages:
33
34                 </p><ul>
35                     <li>You need to stop what you're doing to insert the meta-information, and that breaks your concentration;</li>
36                     <li>If you are lazy or get annoyed and don't keep updating it, the statistics will be useless</li>
37                     <li>You won't be able to catch a little thing like quickly answering an e-mail or looking for the weather report.</li>
38                 </ul>
39
40                 <p><b>arbtt</b>, on the other hand, is a time tracker that <i>gets out of the way</i>.
41                 Its core component (<code>arbtt-capture</code>) silently captures data
42                 about what you are doing, completely autonomously.
43                 No interaction required, no distraction possible.
44                 This information is continuously stored in a log file.
45                 A separate tool (<code>arbtt-stats</code>) the allows you to investigate this data,
46                 at whatever time is convenient to you, by using simple text-based rules.</p>
47
48                 <p>One big advantage of this approach is that you do not need to know in advance
49                 what queries you are interested in.
50                 Since the rules are applied in real-time when you are evaluating your data,
51                 and not when recording it, your raw data is always intact, and
52                 you can add more rules and forgotten special cases later.</p>
53
54                 <blockquote><i> Keep in mind that the log file might contain
55                 very sensitive private data. Make sure you protect it well.<br>
56                 You can get rid of all logs by deleting
57                 <code>~/.arbtt/capture.log</code></i>.</blockquote>
58             </section>
59
60             <section id="how">
61                 <h2>How does it work?</h2>
62
63                 <p><code>arbtt-capture</code> is a desktop daemon that runs in the background
64                 and keeps a continuous log of your activity,
65                 by storing at regular intervals which windows are open,
66                 which one has the focus and how long it has been since your last action.</p>
67
68                 <p>From this log, a wealth of statistics can be derived.
69                 Here's where the "rule-based" part of the name comes along:
70                 arbtt comes with a built-in command-line statistics generator (<code>arbtt-stats</code>)
71                 that will, based on very simple but powerful rules you can customize,
72                 sift through the raw data and reveal patterns and relevant information.
73                 </p>
74                 <p>The rules are specified in a simple text-based format, on a file called
75                 "categorize.cfg". Here's an example of a simple categorize.cfg file:
76                 </p><pre>
77 --Convert program executable names to recognizable names
78 aliases (
79   "Navigator"         -&gt; "Firefox",
80   "evince"            -&gt; "PDF reader",
81   "gedit"             -&gt; "Text editor",
82   "totem"             -&gt; "Video player",
83 )
84
85 {
86 --Mark any samples captured after 5 minutes of inactivity with the "inactive" tag
87 $idle &gt; 300                     ==&gt; tag inactive,
88
89 --Tag each program with its executable name (filtered by the aliases above)
90                                     tag Program:$current.program,
91
92 --Tag each program with its window title (filtered by the aliases above)
93                                     tag Title:$current.title,
94
95 $time &gt;=  8:00 &amp;&amp; $time &lt; 12:00 ==&gt; tag time-of-day:morning,
96 $time &gt;= 14:00 &amp;&amp; $time &lt; 18:00 ==&gt; tag time-of-day:afternoon,
97 }</pre>
98
99                 <p>And here's the corresponding output of <code>arbtt-stats -c "Program"</code>:</p>
100                 <pre>
101 Statistics for category "Program"
102 =================================
103 __________________Tag_|_________Time_|_Percentage_
104       Program:Firefox |  8d06h20m00s |      49.01
105 Program:Google Chrome |  3d15h24m00s |      21.60
106   Program:Text editor |  1d04h04m00s |       6.94
107         Program:Skype |    13h55m00s |       3.44
108      Program:Terminal |     9h22m00s |       2.31
109    Program:PDF reader |     6h10m00s |       1.52
110       Program:Desktop |     5h13m00s |       1.29
111  Program:File browser |     4h11m00s |       1.03
112  (53 entries omitted) |    22h59m00s |       5.68</pre>
113
114             </section>
115
116             <section id="install">
117                 <h2>Install arbtt</h2>
118                 <ul class="installation">
119                   <h3>Binary installations</h3>
120                     <li>
121                         <b>Debian/Ubuntu:</b>
122                         <p>arbtt is available both in
123                         <a href="http://packages.debian.org/sid/arbtt">Debian's</a> and
124                         <a href="http://packages.ubuntu.com/raring/arbtt">Ubuntu's</a> repositories.</p>
125                         <p>Install arbtt:</p>
126                         <code class="command">sudo apt-get install arbtt</code>
127                         <p>Set it up to start automatically on system startup:</p>
128                         <code class="command">cp /usr/share/doc/arbtt/examples/arbtt-capture.desktop ~/.config/autostart/</code>
129                         <p>Start the daemon manually, if you want it to start capturing immediately,
130                         rather than at the next system restart:</p>
131                         <code class="command">(arbtt-capture &amp;)</code>
132                         <p>Create a minimal categorize.cfg file to allow arbtt-stats to be invoked without errors:</p>
133                         <code class="command">echo "{\$idle &gt; 60 ==&gt; tag inactive}" &gt; ~/.arbtt/categorize.cfg</code>
134                     </li>
135                     <li>
136                         <b>Windows:</b><br>Download the
137                         latest <a href="http://www.joachim-breitner.de/archive/arbtt/">arbtt-setup.exe</a>
138                         and follow the setup process as usual. This will set up the capturing daemon,
139                         but note that there is no graphical interface. Extracting stats from the data
140                         requires running arbtt-stats on the command line. Run
141                         <code>arbtt-stats --help</code> for a quick reference;
142                         for more detailed information, consult the
143                         <a href="doc/users_guide/arbtt-stats.html">manual</a>.
144                     </li>
145                     <h3>Source installations</h3>
146
147                       <p>arbtt can be installed from source either via cabal install or from the source repository.</p>
148                       <b>Dependencies:</b>
149                       <p>arbtt depends on several libraries whose development versions (name often suffixed <code>-dev</code>) must be available or the compilation
150                         may fail with errors such as <code>X11-1.6.1.2 failed during the configure step</code>;
151                         these libraries include:
152                         <ul>
153                           <li>X11, for the X11 Haskell binding (possibly named <code>libx11-dev</code> or <code>xorg-dev</code> in your package manager)</li>
154                           <li>PCRE3, for pcre-light (possibly <code>libpcre3-dev</code>)</li>
155                           <li>XSS, for arbtt (possibly <code>libxss-dev</code>)</li>
156                         </ul>
157                       </p>
158                     <li>
159                       <b>From Hackage:</b>
160                       <p>arbtt has been <a href="http://hackage.haskell.org/package/arbtt">published on hackage</a>,
161                         the Haskell package database. If you have
162                         <a href="http://www.haskell.org/haskellwiki/Cabal-Install">cabal-install</a>
163                         available, you can install arbtt by simply running:</p>
164                         <code class="command">cabal install arbtt</code>
165                     </li>
166
167                     <li>
168                         <b>Build from repo:</b>
169                         <p>Download the latest release from <a href="http://www.joachim-breitner.de/archive/arbtt/">the archive</a>.
170                         Extract the tarball and run the following commands to build and install the arbtt binaries:</p>
171                         <code class="command">runhaskell Setup.hs configure</code><br>
172                         <code class="command">runhaskell Setup.hs build</code><br>
173                         <code class="command">runhaskell Setup.hs install</code><br>
174                         <p>If you use GNOME or KDE, you can copy the file "arbtt-capture.desktop"
175                         to ~/.config/autostart/. If you didn't do a system-wide installation,
176                         you'll probably need to put the full path to arbtt-capture
177                         in the Exec line of the .desktop file.</p>
178                     </li>
179
180                     <li>
181                         <b>Mac OS X support:</b>
182                         <p>arbtt can run on Mac OS X systems. To compile it, you need to install the pkgconfig and pcre source packages
183                         using <a href="http://brew.sh">Homebrew</a> or <a href="https://www.macports.org">MacPorts</a>. For Homebrew, you can execute:</p>
184                         <code class="command">brew install pkgconfig</code><br>
185                         <code class="command">brew install pcre</code><br>
186                         <p>or for MacPorts:</p>
187                         <code class="command">sudo port install pkgconfig</code><br>
188                         <code class="command">sudo port install pcre</code><br>
189                         <p>Then, you can compile arbtt using the usual cabal commands.</p>
190                         <p>If you use MacPorts and have a linking error, it may be because of a conflict between the system libiconv and the MacPorts libiconv.
191                         Execute the following cabal command to resolve the conflict:</p>
192                         <code class="command">cabal configure --extra-lib-dir=/usr/lib</code><br>
193                         <p>When the installation is done, your arbtt binaries will be located in <code>~/Library/Haskell/bin</code> or <code>~/.cabal/bin</code>.</p>
194                     </li>
195                 </ul>
196             </section>
197
198             <section id="contact">
199                 <h2>Get in touch</h2>
200                 <h3>Mailing list</h3>
201                     <p>
202 The main communication channel is the arbtt mailing list,
203 <code>arbtt@lists.nomeata.de</code>, which is used for both users and
204 developers of arbtt. If you have questions about arbtt, want to report bugs, or
205 just share your experience with it, please join. Also any contributions in the
206 form of ideas, code or documentation is highly appreciated. To subscribe to it,
207 visit <a href="https://lists.nomeata.de/mailman/listinfo/arbtt">the mailinglist page</a>.</p>
208
209                 <h3>Issue tracker</h3>
210                     <p>
211 In addition to the mailing list, we use the <a href="https://bitbucket.org/nomeata/arbtt/issues">issue tracker of the bitbucket repository</a>. Why BitBucket, and not GitHub? Becuase we need diversity, even and especially in the cloud! But do not worry, you can use your GitHub account there.
212                                 </p>
213
214                 <h3>Developement repository</h3>
215 <p>The source code is in <a href="http://haskell.org">Haskell</a>,
216 and is managed in a darcs<sup>☆</sup> repository
217 (<a href="http://darcs.nomeata.de/cgi-bin/darcsweb.cgi?r=arbtt;a=summary">browse it online</a>).
218 You can fetch the code with:<br>
219 <code class="command">darcs get http://darcs.nomeata.de/arbtt</code></p>
220
221 <blockquote><i><sup>☆</sup><a href="http://darcs.net/">darcs</a> is a
222 distributed version control system, very similar to git and easy to get started
223 with. Here's an excellent <a href="http://darcs.net/QuickStart?export&amp;format=Slidy">quickstart
224 slideshow</a> for getting acquainted with the basics.</i></blockquote>
225
226 <p>Git mirrors are available at:</p>
227 <ul>
228 <li><a href="http://git.nomeata.de/?p=darcs-mirror-arbtt.git">http://git.nomeata.de/?p=darcs-mirror-arbtt.git</a><br /></li>
229 <li><a href="https://github.com/nomeata/darcs-mirror-arbtt">https://github.com/nomeata/darcs-mirror-arbtt</a><br /></li>
230 <li><a href="https://bitbucket.org/nomeata/arbtt">https://bitbucket.org/nomeata/arbtt</a></li>
231 </ul>
232
233                 <h3>History and credits</h3>
234 <p>Arbtt was created in 2009 by <a href="http://www.joachim-breitner.de/">Joachim Breitner</a>. This webpage was designed by Waldir Pimenta in 2013. The background image is <a href="http://commons.wikimedia.org/wiki/File:Revolutionstaschenuhr.jpg">Revolutionstaschenuhr</a> by Onnahfarg; CC-BY</p>.
235             </section>
236         </div>
237     </div>
238     <script src="arbtt.js"></script>
239 </body>
240 </html>