Documentation updates for 3.73 - 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-wav
84                 
85                 This enables the builtin wav routines. They load 16Bit/44Khz
86                 MONO RIFF/WAV files only but they do that significantly faster
87                 than using sox. If these routines fail and sox support is
88                 enabled, terminatorX will try to load the file with sox as 
89                 a fallback. Disable them only if they don't load your files
90                 correctly.
91                 
92                 --enable-sox
93                 
94                 This enables sox support. As sox can load nearly any audio file
95                 it makes sense to use it. You have to have sox installed of 
96                 course.
97                 
98                 --enable-mpg123
99                 
100                 This enables mpg123 support. If you want to be able to load mp3
101                 files keep this option enabled. You have to have mpg123
102                 installed of course.
103                 
104                 --enable-ogg123
105                 
106                 With this option you can turn on/off support for Ogg Vorbis
107                 soundfiles. This requires ogg123 (Version >= 1.0RC2) and
108                 sox to be installed. 
109                 
110                 Other options:
111                 -------------
112                 
113                 --disable-gtk2
114                 
115                 If you've got gtk+ V2 installed but you want terminatorX to use
116                 the old gtk+ V1.2 for some reason, use this switch to disable
117                 gtk+ V2 code.
118                 
119                 --disable-libxml2
120                 
121                 If you've got libxml V2 installed but you want terminatorX to 
122                 use V1 instead, use this to disable libxml V1.
123
124                 --enable-debug
125                 
126                 This will cause terminatorX to display some debug messages on
127                 your console. 
128                 
129                 Just as an example my configure line is (works with bash only):
130                 > CFLAGS="-O3 -mathlon" ./configure 
131
132 Step 2: Build the binary.
133 -------------------------
134
135         This one's easy:
136         > make
137         
138 Step 3: Install the binary:
139 ---------------------------
140
141         Just as easy:
142         > make install
143         
144         You need root privileges though. If you don't have them simply copy
145         the terminatorX-binary (in src/terminatorX) to a directory of your
146         choice and run terminatorX form there.