Adding support for writing zlib compressed set files and fixing audio

[terminatorX.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 6dfb06eea67eb90e08df669c1b1108bf0e53870a..1fc776e53290cd9c121bb2235b669de5a261f5d4 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,5 +1,9 @@
 terminatorX INSTALL:
 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. To get LADSPA visit http: http://www.ladspa.org

 
 Quickstart:
 -----------
 
 Quickstart:
 -----------


@@ -21,8 +25,8 @@ Step 1: Configure terminatorX.
        if use bash: > export CFLAGS="-O2"
        with tcsh:   > setenv CFLAGS "-O2"
 
        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.
 
        All of the following configure options can be either enabled with
        --enable-option or disabled with --disable-option.


@@ -34,46 +38,38 @@ Step 1: Configure terminatorX.
                
                --enable-scheduler
                
                
                --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
                
                
                > chown root terminatorX
                > chmod u+s terminatorX
                

-               I WARNED YOU! Anybody who can run this binary can completely
-               erase your hardisk. BE CAREFUL.
-               
-               --disable-flash
-               
-               This turns off the "flash"-widgets that display the current
-               signal of the turntables and the master out. This might help
-               fighting performance probs. Oh, If you have a better name
-               for the widget please tell me ;)                
-               
-               --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:
                ---------------------
                
                File support options:
                ---------------------
                


@@ -84,6 +80,27 @@ Step 1: Configure terminatorX.
                them - or check your distribution first, AFAIK all bring these
                tools nowaday.
                
                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
                --enable-wav
                
                This enables the builtin wav routines. They load 16Bit/44Khz


@@ -105,25 +122,33 @@ Step 1: Configure terminatorX.
                files keep this option enabled. You have to have mpg123
                installed of course.
                
                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:

                -------------
                
                -------------
                

-               --disable-dial
+               --disable-gtk2

                
                

-               The resulting binary will not use the new dial-widget, but
-               scales instead.
-
-               --enable-closedev
+               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.

                
                

-               This has no effect at the moment. Sorry. Don't disable it.
+               --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):
                --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.
 -------------------------
 
 Step 2: Build the binary.
 -------------------------