Adding support for writing zlib compressed set files and fixing audio
[terminatorX.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index ff0cb0a0e52f5bb1b4b2c70408178c38b1a750ce..1fc776e53290cd9c121bb2235b669de5a261f5d4 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,8 +1,9 @@
 terminatorX INSTALL:
-Copyright (C) 1999, 2000 by Alexander König <alkoit00@fht-esslingen.de>
+Copyright (C) 1999 - 2003 by Alexander König <alex@lisas.de>
+http://terminatorX.cx
 
 Note: As of Version 3.70 you need to have LADSPA installed to compile
-terminatorX.
+terminatorX. To get LADSPA visit http: http://www.ladspa.org
 
 Quickstart:
 -----------
@@ -24,8 +25,8 @@ Step 1: Configure terminatorX.
        if use bash: > export CFLAGS="-O2"
        with tcsh:   > setenv CFLAGS "-O2"
 
-       I use CFLAGS="-O6 -mpentiumpro" btw. You'll need to have a
-       "pentium-aware" compiler to use that though (gcc/pgcc).
+       I use CFLAGS="-O3 -mathlon" btw. You'll need to have a
+       "athlon-aware" compiler to use that though (gcc > 2.95.?).
 
        All of the following configure options can be either enabled with
        --enable-option or disabled with --disable-option.
@@ -37,39 +38,38 @@ Step 1: Configure terminatorX.
                
                --enable-scheduler
                
-               NEW: since 3.5 this option is enabled by default, as you can
-               now operate the GUI while sound is playing, which can cause 
-               audio dropouts when the GUI and the sound thread run at the
-               same priority. You still need root privileges though.
-               
-               If you run terminatorX compiled with this option as root, the
-               engine thread will be run with FIFO-scheduling policy at the 
-               highest priority. This is somewhat dangerous I guess, as is
-               running programs as root anyway ;) If you want everybody to
-               run terminatorX as root (THIS IS DANGEROUS AND YOU SHOULD NOT
-               DO IT) cd (as root) into the directory where you installed
-               terminatorX (usually /usr/local/bin) and execute:
+               This option is now enabled by default. When run with root 
+               privileges terminatorX creates the engine thread with realtime
+               scheduling priorities which should result in much better
+               playback performance. Since Version 3.73 terminatorX supports
+               running suid root. If you install the terminatorX binary suid
+               root with the following commands: (with the default install
+               you should find the terminatorX binary in /usr/local/bin)
                
                > chown root terminatorX
                > chmod u+s terminatorX
                
-               I WARNED YOU! Anybody who can run this binary can completely
-               erase your hardisk. BE CAREFUL.
-               
-               --enable-3dnow
-               
-               This enables EXPERIMENTAL 3DNow! support. It seems as if the
-               current libmmx (which is included) doesn't work with the new
-               gcc 2.95. So if you use that compiler do not enable this option.
-               
-               The built binary will run on CPUs with 3DNow! support only.
-               AFAIK these are the K6II, K6III and the Athlon (K7). INTEL CPUs
-               don't have 3DNow! support!
-               
-               For now this the only thing that might run a little faster is
-               the echo effect. I planned to hack more 3DNow! code but at the
-               moment I simply don't have the time.
-                               
+               terminatorX will be started with root privileges even when an
+               "unprivileged" user runs the binary. terminatorX will then 
+               create the engine thread with realtime priority before any files
+               are written, any parameters are evaluated or connections to the 
+               X11 display are established. Right after that terminatorX will
+               drop root privileges, so the actual terminatorX code runs 
+               unprivileged.
+               
+               The problem is, with Linux' pthreads implementation the pthread
+               manager thread (that can not be influenced by terminatorX) will 
+               still run with root privileges.
+               
+               So there is a small chance that a malicious attacker could 
+               utilize terminatorX to acquire root privileges if installed suid
+               root, although it should require quite some effort to create an
+               exploit for that. On the other hand realtime scheduling 
+               massively improves the playback performance. So depending on who
+               can access your computer you will have to decide for yourself on
+               performance vs security. Alternatively you can of course run
+               terminatorX as root to achieve realtime scheduling.
+                                               
                File support options:
                ---------------------
                
@@ -80,6 +80,27 @@ Step 1: Configure terminatorX.
                them - or check your distribution first, AFAIK all bring these
                tools nowaday.
                
+               --enable-mad
+               
+               This will make terminatorX use the MPEG Audio Decoder library if 
+               it's detected. This allows terminatorX to load mp3 files
+               significantly faster than with the mpg123 method. Additionally
+               terminatorX will find out about the sampling rate of an mp3 file
+               and adjust the playback speed accordingly.
+               
+               --enable-vorbis
+               
+               This will make terminatorX use the OGG Vobris libraries to load
+               OGG files directly. This method has the same advantages over 
+               loading through ogg123 as the "mad" method has over loading 
+               through mpg123.
+               
+               --enable-audiofile
+               
+               This enables the use of libaudiofile on loading audio files.
+               The library supports a wide range of common audio file formats
+               (eg WAV/AIFF/AU etc) therefor its use highly recommended.
+               
                --enable-wav
                
                This enables the builtin wav routines. They load 16Bit/44Khz
@@ -101,20 +122,33 @@ Step 1: Configure terminatorX.
                files keep this option enabled. You have to have mpg123
                installed of course.
                
-               Misc options:
+               --enable-ogg123
+               
+               With this option you can turn on/off support for Ogg Vorbis
+               soundfiles. This requires ogg123 (Version >= 1.0RC2) and
+               sox to be installed. 
+               
+               Other options:
                -------------
-
-               --enable-closedev
                
-               This has no effect at the moment. Sorry. Don't disable it.
+               --disable-gtk2
+               
+               If you've got gtk+ V2 installed but you want terminatorX to use
+               the old gtk+ V1.2 for some reason, use this switch to disable
+               gtk+ V2 code.
                
+               --disable-libxml2
+               
+               If you've got libxml V2 installed but you want terminatorX to 
+               use V1 instead, use this to disable libxml V1.
+
                --enable-debug
                
                This will cause terminatorX to display some debug messages on
                your console. 
                
                Just as an example my configure line is (works with bash only):
-               > CFLAGS="-O2 -mpentiumpro" ./configure 
+               > CFLAGS="-O3 -mathlon" ./configure 
 
 Step 2: Build the binary.
 -------------------------