X-Git-Url: https://ruderich.org/simon/gitweb/?p=coloredstderr%2Fcoloredstderr.git;a=blobdiff_plain;f=README;h=46636c5a33d86bf0dafdec5e9c30e520b5d5b40f;hp=482750924e6867e23b60631c3511ae82ee243f21;hb=3e894f0f32aa021b5c9033c3c71539c3965aa6de;hpb=b950cdb79209e092d20d629bd1b0e9211647bd1e

diff --git a/README b/README
index 4827509..46636c5 100644
--- a/README
+++ b/README
@@ -1,15 +1,15 @@
 README
 ======
 
-coloredstderr is a small library which uses 'LD_PRELOAD' to color stderr.
-
+coloredstderr is a small library which uses 'LD_PRELOAD' to color stderr. It
+``follows'' dups, has minimal performance overhead and can ignore certain
+binaries.
 
 Like all solutions using 'LD_PRELOAD' it only works with dynamically linked
 binaries. Statically linked binaries, for example valgrind, are not supported.
 setuid binaries are also not supported ('LD_PRELOAD' disabled for security
 reasons).
 
-
 It was inspired by stderred [2]. Similar solutions (using 'LD_PRELOAD')
 include:
 
@@ -23,19 +23,26 @@ include:
 Most other existing solutions use a second process which colors its input and
 pipe stderr to it. However this creates different runtime behaviour resulting
 in a different ordering of the output. Partial lines (no newline) also often
-cause problems.
+cause problems. coloredstderr handles these cases correctly (but has other
+possible issues, see below).
+
+coloredstderr is licensed under GPL 3 (or later).
 
 
 DEPENDENCIES
 ------------
 
 - C99 compiler (variable length arrays)
-- dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's ld.so)
+- dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's or
+  FreeBSD's ld.so)
 
 
 INSTALLATION
 ------------
 
+If you're using the Git version, run `autoreconf -fsi` first to generate
+`configure`.
+
     ./configure && make && make check
 
 Then either install the library with `make install` or just copy it from
@@ -81,6 +88,27 @@ A default setup could look like this:
     COLORED_STDERR_FDS=2,
     export LD_PRELOAD COLORED_STDERR_FDS
 
+To use coloredstderr with multi-lib (multiple architectures on the same
+system, e.g. i386 and amd64), your system must support the '$LIB' variable in
+'LD_PRELOAD'. Then you can build coloredstderr for all architectures and use
+'$LIB' in 'LD_PRELOAD'. The following should work for Debian-based systems
+with this directory structure:
+
+    dir
+    `-- lib
+        |-- i386-linux-gnu
+        |   `-- libcoloredstderr.so
+        `-- x86_64-linux-gnu
+            `-- libcoloredstderr.so
+
+Now set 'LD_PRELOAD'. `lib/` is included in '$LIB'!
+
+    LD_PRELOAD='/absolute/path/to/dir/$LIB/libcoloredstderr.so'
+
+The single quotes are important. '$LIB' is not evaluated by the shell, but by
+the loader (`man ld.so`). Now both i386 and amd64 binaries automatically use
+coloredstderr.
+
 
 The following additional environment variables are available:
 
@@ -95,8 +123,9 @@ The following additional environment variables are available:
   are colored.
 - 'COLORED_STDERR_IGNORED_BINARIES'
   Comma separated list of binary names/paths which should not be tracked
-  (including their children). Useful for `reset` which writes to the terminal
+  (including their children). Useful for `reset` which writes to the terminal,
   but fails to work if the output is colored. See below for an example.
+  Requires `/proc/self/exe`.
 
 All environment variables starting with 'COLORED_STDERR_PRIVATE_*' are
 internal variables used by the implementation and should not be set manually.
@@ -113,11 +142,11 @@ Or to be more compatible you can use the following which should work in any
 Bourne shell:
 
     esc=`printf '\033'`
-    COLORED_STDERR_PRE="${esc}[91m" # red
+    COLORED_STDERR_PRE="${esc}[91m" # bright red
     COLORED_STDERR_POST="${esc}[0m" # default
     export COLORED_STDERR_PRE COLORED_STDERR_POST
 
-Fix `reset`; its writes to the terminal must be unaltered. `reset` is
+Fix `reset`; its writes to the terminal must be unaltered. `reset` is a
 symbolic-link to `tset` on some systems, adapt as necessary:
 
     COLORED_STDERR_IGNORED_BINARIES=/usr/bin/tset
@@ -149,12 +178,15 @@ warnings are appended at the end.
 KNOWN ISSUES
 ------------
 
-- `{fputc,putc,putchar}_unlocked()` are not hooked when writing to stdout
-  (which might be redirected to stderr). Can't be fixed as the compiler
+- `{fputc,putc,putchar}_unlocked()` are not hooked with glibc when writing to
+  stdout (which might be redirected to stderr). Can't be fixed as the compiler
   inlines the code into the program without calling any function.
-- Test `test_stdio.sh` fails for this reason on FreeBSD.
-- 'COLORED_STDERR_IGNORED_BINARIES' requries the `/proc` file system.
-  Suggestions welcome.
+- Test `test_stdio.sh` fails on FreeBSD, because FreeBSD does handle the above
+  correctly (no inlining), but the test is designed for GNU/Linux.
+- 'COLORED_STDERR_IGNORED_BINARIES' requires `/proc/self/exe`. Suggestions
+  welcome.
+- Output of `strace` is not always colored correctly as the output from
+  `coloredstderr` is traced and displayed as well. Suggestions welcome.
 
 
 BUGS
@@ -175,7 +207,7 @@ LICENSE
 
 coloredstderr is licensed under GPL version 3 or later.
 
-Copyright (C) 2013  Simon Ruderich
+Copyright (C) 2013-2014  Simon Ruderich
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by