Allow nightly to fail, until all dependencies are present.
[darcs-mirror-arbtt.git] / README.md
1 arbtt, the Automatic Rule-Based Time Tracker
2 ============================================
3
4 © 2009 Joachim Breitner <mail@joachim-breitner.de>
5
6 The Automatic Rule-Based Time Tracker is a desktop daemon that runs in the
7 background and, every minute, records what windows are open on your
8 desktop, what their titles are, which one is active. The accompanied
9 statistics program lets you derive information from this log file, i.e.
10 what how much of your time have you been spending with e-Mail, or what
11 projects are your largest time wasters. The mapping from the raw window
12 titles to sensible „tags“ is done by a configuration file with an powerful
13 syntax.
14
15 Installation
16 ------------
17
18 You can build and install this program as any other Cabalized program:
19
20     $ runhaskell Setup.hs configure
21     $ runhaskell Setup.hs build
22     $ runhaskell Setup.hs install
23
24 You also need to make sure that arbtt-capture is started with your X
25 session. If you use GNOME or KDE, you can copy the file
26 `arbtt-capture.desktop` to `~/.config/autostart/`. You might need to put the
27 full path to arbtt-capture in the `Exec` line there, if you did not do a
28 system wide installation.
29
30 If you want to record samples at a different rate than one per minute, you
31 will have to pass the `--sample-rate` parameter to arbtt-capture.
32
33 Documentation
34 ------------
35
36 Full documentation is now provided in the user manual in the doc/
37 directory. If you have the docbook xsl toolchain installed, you can
38 generate the HTML documentation by entering "make" in that directory.
39 Otherwise, you can use the
40 [online version of the User’s Guide](http://darcs.nomeata.de/arbtt/doc/users_guide/)
41 Beware that this will also reflect the latest development version.
42
43 Development
44 -----------
45
46 You are very welcome to help the developement of arbtt. You can find the
47 latest source at the darcs repository at
48   http://darcs.nomeata.de/arbtt
49
50 Git mirrors are available at
51
52  * http://git.nomeata.de/?p=darcs-mirror-arbtt.git
53  * https://github.com/nomeata/darcs-mirror-arbtt
54  * https://bitbucket.org/nomeata/arbtt
55
56 User and Developer discussion happens on the arbtt mailing list:
57   arbtt@lists.nomeata.de
58 To subscribe to the list, visit:
59   http://lists.nomeata.de/mailman/listinfo/arbtt
60
61 The issue tracker is hosted on bitbucket:
62   https://bitbucket.org/nomeata/arbtt/issues
63 Why Bitbucket and not GitHub? Why not, and we need diversitiy even in the
64 cloud! (Don’t worry, you can use your GitHub account there.)
65
66 Some of my plans or ideas include:
67
68  * A graphical viewer that allows you to expore the tags in an appealing,
69    interactive way. Possibly based on the Charts haskell library.
70  * Looking forward and backwards in time when writing rules. (Information
71    is already passed to the categorizing function, but not exposed to the
72    syntax).
73  * `$total_idle` time, which is the maximum idle time until it is reset. This
74    would allow the user to catch the idle times more exactly.
75  * Rules based on time of day, to create tags for worktime, weekend, late
76    at night. (Partially done)
77  * Storing the current timezone in the tags, for the prevoius entry to be
78    more to be more useful.
79  * Storing the hostname, in case a user has several. 
80  * Statistics based on time, to visualize trends.
81  * Possibly more data sources?
82
83 Any help cleaning, documenting or testing the current code is appreciated
84 as well.
85
86 Creating the Windows Installer
87 ------------------------------
88
89 The file `setup.iss` contains an installer script for Inno Setup and can be used
90 to create the windows installer for arbtt. It can be used under wine. To build
91 arbtt under Windows, you need to install the Haskell Platform. Because the
92 Haskell Platform ships an older version of the w32api package from mingw, you
93 also need to download `w32api-3.14-mingw32-dev.tar.gz` and copy at least the files
94 `include/psapi.h` and `lib/libpsapi.a` over the files installed by the Haskell
95 Platform. For the `pcre-light` package, you need to install the `pcre` library.
96 Unless you run a German version of Windows, you’ll need to adjust the path to
97 the `pcre3.dll` file in `setup.iss`. Install `Inno Setup`. Create the documentation
98 (`make -C doc`) and configure arbtt with the `--with-ISCC-flag`:
99
100     $ wine runhaskell Setup.hs configure --with-ISCC='C:\Programme\Inno Setup 5\ISCC.exe'
101
102 again adjusting the path if you do not have a German version of Windows. This
103 will put the version name into `setup.iss` and create the output file as
104 `dist/arbtt-setup-<version>.exe.`
105
106 Download links:
107
108  * http://hackage.haskell.org/platform/2009.2.0.2/HaskellPlatform-2009.2.0.2-setup.exe
109  * http://sourceforge.net/projects/mingw/files/MinGW%20API%20for%20MS-Windows/
110  * http://gnuwin32.sourceforge.net/downlinks/pcre.php
111  * http://www.jrsoftware.org/download.php/is-unicode.exe
112