Adding support for writing zlib compressed set files and fixing audio

[terminatorX.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 062654cad9daa4f49a7b6fef550ce512478454b2..1fc776e53290cd9c121bb2235b669de5a261f5d4 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,5 +1,9 @@
 terminatorX INSTALL:
 terminatorX INSTALL:

-Copyright (C) 1999 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,52 +25,130 @@ 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="-O7 -mpentium" btw. You'll need to have a "pentium-aware"
-       compiler to use that though (egcs-pgcc).
-
-       The configure Options:
+       I use CFLAGS="-O3 -mathlon" btw. You'll need to have a
+       "athlon-aware" compiler to use that though (gcc > 2.95.?).

 
 

-               --enable-wavonly
+       All of the following configure options can be either enabled with
+       --enable-option or disabled with --disable-option.

 
 

-               Since Version 3.2 the terminatorX configure script automatically
-               enables sox and mpg123 support, if these programs are found on
-               the target system. So to be able to load close to any audiofile
-               simply ensure you have sox and mpg123 installed an run the
-               configure script - if you want to use the builtin wav-loading
-               routines specify --enable-wavonly. These will be enabled if
-               sox is not found of course.
-               
-               WARNING: Loading mp3's usually takes quite some time and 
-               requires a whole lot of memory! tX does not support on-the-fly
-               mp3 decoding, and therefor the whole mp3 will be decoded (by
-               mpg123) before tX can handle the data.
+       The configure Options:
+       
+               Performance Options:
+               --------------------

                
                --enable-scheduler
                
                
                --enable-scheduler
                

-               This option is only intended for people who have audiobuffer
-               underruns (clicks) with their desired latency settings.
-               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.
+               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:
+               ---------------------
+               
+               All of these are enabled by default. Nevertheless the configure
+               script checks for the availability of the helper application
+               and if it's not found disables support for it. Check the
+               terminatorX homepage for links to those apps if you don't have
+               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-closedev=no
+               --enable-wav

                
                

-               The old "KEEP_DEV_OPEN" flag. Still does the same thing: Once
-               the audiodevice is opened it won't be closed until you exit
-               terminatorX. Good for devices that click when opened.
+               This enables the builtin wav routines. They load 16Bit/44Khz
+               MONO RIFF/WAV files only but they do that significantly faster
+               than using sox. If these routines fail and sox support is
+               enabled, terminatorX will try to load the file with sox as 
+               a fallback. Disable them only if they don't load your files
+               correctly.
+               
+               --enable-sox
+               
+               This enables sox support. As sox can load nearly any audio file
+               it makes sense to use it. You have to have sox installed of 
+               course.
+               
+               --enable-mpg123
+               
+               This enables mpg123 support. If you want to be able to load mp3
+               files keep this option enabled. You have to have mpg123
+               installed of course.
+               
+               --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-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):
                Just as an example my configure line is (works with bash only):

-               > CFLAGS="-O7 -mpentium" ./configure 
+               > CFLAGS="-O3 -mathlon" ./configure 

 
 Step 2: Build the binary.
 -------------------------
 
 Step 2: Build the binary.
 -------------------------