Spec stuff - Alex
[terminatorX.git] / INSTALL
1 terminatorX INSTALL:
2 Copyright (C) 1999, 2000, 2001 by Alexander K├Ânig <alex@lisas.de>
3 http://terminatorX.cx
4
5 Note: As of Version 3.70 you need to have LADSPA installed to compile
6 terminatorX. To get LADSPA visit http: http://www.ladspa.org
7
8 Quickstart:
9 -----------
10
11         If you want enhanced audio-file support or optimization don't
12         "quickstart" but read the rest of this file.
13
14         If you just cant wait any longer try:
15         > ./configure
16         > make install
17
18 Step 1: Configure terminatorX.
19 ------------------------------
20
21         If you want your compiler to optimize the binary, you need to set your
22         environment variable CFLAGS to your needs BEFORE you run ./configure.
23
24         for example:
25         if use bash: > export CFLAGS="-O2"
26         with tcsh:   > setenv CFLAGS "-O2"
27
28         I use CFLAGS="-O3 -mathlon" btw. You'll need to have a
29         "athlon-aware" compiler to use that though (gcc > 2.95.?).
30
31         All of the following configure options can be either enabled with
32         --enable-option or disabled with --disable-option.
33
34         The configure Options:
35         
36                 Performance Options:
37                 --------------------
38                 
39                 --enable-scheduler
40                 
41                 This option is now enabled by default. When run with root 
42                 privileges terminatorX creates the engine thread with realtime
43                 scheduling priorities which should result in much better
44                 playback performance. Since Version 3.73 terminatorX supports
45                 running suid root. If you install the terminatorX binary suid
46                 root with the following commands: (with the default install
47                 you should find the terminatorX binary in /usr/local/bin)
48                 
49                 > chown root terminatorX
50                 > chmod u+s terminatorX
51                 
52                 terminatorX will be started with root privileges even when an
53                 "unprivileged" user runs the binary. terminatorX will then 
54                 create the engine thread with realtime priority before any files
55                 are written, any parameters are evaluated or connections to the 
56                 X11 display are established. Right after that terminatorX will
57                 drop root privileges, so the actual terminatorX code runs 
58                 unprivileged.
59                 
60                 The problem is, with Linux' pthreads implementation the pthread
61                 manager thread (that can not be influenced by terminatorX) will 
62                 still run with root privileges.
63                 
64                 So there is a small chance that a malicious attacker could 
65                 utilize terminatorX to acquire root privileges if installed suid
66                 root, although it should require quite some effort to create an
67                 exploit for that. On the other hand realtime scheduling 
68                 massively improves the playback performance. So depending on who
69                 can access your computer you will have to decide for yourself on
70                 performance vs security. Alternatively you can of course run
71                 terminatorX as root to achieve realtime scheduling.
72                                                 
73                 File support options:
74                 ---------------------
75                 
76                 All of these are enabled by default. Nevertheless the configure
77                 script checks for the availability of the helper application
78                 and if it's not found disables support for it. Check the
79                 terminatorX homepage for links to those apps if you don't have
80                 them - or check your distribution first, AFAIK all bring these
81                 tools nowaday.
82                 
83                 --enable-mad
84                 
85                 This will make terminatorX use the MPEG Audio Decoder library if 
86                 it's detected. This allows terminatorX to load mp3 files
87                 significantly faster than with the mpg123 method. Additionally
88                 terminatorX will find out about the sampling rate of an mp3 file
89                 and adjust the playback speed accordingly.
90                 
91                 --enable-vorbis
92                 
93                 This will make terminatorX use the OGG Vobris libraries to load
94                 OGG files directly. This method has the same advantages over 
95                 loading through ogg123 as the "mad" method has over loading 
96                 through mpg123.
97                 
98                 --enable-audiofile
99                 
100                 This enables the use of libaudiofile on loading audio files.
101                 The library supports a wide range of common audio file formats
102                 (eg WAV/AIFF/AU etc) therefor its use highly recommended.
103                 
104                 --enable-wav
105                 
106                 This enables the builtin wav routines. They load 16Bit/44Khz
107                 MONO RIFF/WAV files only but they do that significantly faster
108                 than using sox. If these routines fail and sox support is
109                 enabled, terminatorX will try to load the file with sox as 
110                 a fallback. Disable them only if they don't load your files
111                 correctly.
112                 
113                 --enable-sox
114                 
115                 This enables sox support. As sox can load nearly any audio file
116                 it makes sense to use it. You have to have sox installed of 
117                 course.
118                 
119                 --enable-mpg123
120                 
121                 This enables mpg123 support. If you want to be able to load mp3
122                 files keep this option enabled. You have to have mpg123
123                 installed of course.
124                 
125                 --enable-ogg123
126                 
127                 With this option you can turn on/off support for Ogg Vorbis
128                 soundfiles. This requires ogg123 (Version >= 1.0RC2) and
129                 sox to be installed. 
130                 
131                 Other options:
132                 -------------
133                 
134                 --disable-gtk2
135                 
136                 If you've got gtk+ V2 installed but you want terminatorX to use
137                 the old gtk+ V1.2 for some reason, use this switch to disable
138                 gtk+ V2 code.
139                 
140                 --disable-libxml2
141                 
142                 If you've got libxml V2 installed but you want terminatorX to 
143                 use V1 instead, use this to disable libxml V1.
144
145                 --enable-debug
146                 
147                 This will cause terminatorX to display some debug messages on
148                 your console. 
149                 
150                 Just as an example my configure line is (works with bash only):
151                 > CFLAGS="-O3 -mathlon" ./configure 
152
153 Step 2: Build the binary.
154 -------------------------
155
156         This one's easy:
157         > make
158         
159 Step 3: Install the binary:
160 ---------------------------
161
162         Just as easy:
163         > make install
164         
165         You need root privileges though. If you don't have them simply copy
166         the terminatorX-binary (in src/terminatorX) to a directory of your
167         choice and run terminatorX form there.