NEWS: improve 0.2 notes

[coloredstderr/coloredstderr.git] / README

diff --git a/README b/README
index 5e2209efdd37a5c29813359150938da8f770e31f..46636c5a33d86bf0dafdec5e9c30e520b5d5b40f 100644 (file)
--- a/README
+++ b/README
@@ -1,15 +1,15 @@
 README
 ======
 
 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).
 
 
 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:
 
 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
 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)
 
 
 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
 ------------
 
 
 
 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
     ./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
 
     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:
 
 
 The following additional environment variables are available:
 


@@ -93,6 +121,11 @@ The following additional environment variables are available:
   If set to an non-empty value add pre/post strings even when not writing to a
   terminal, e.g. when writing to a file. By default, only writes to a terminal
   are colored.
   If set to an non-empty value add pre/post strings even when not writing to a
   terminal, e.g. when writing to a file. By default, only writes to a terminal
   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,
+  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.
 
 All environment variables starting with 'COLORED_STDERR_PRIVATE_*' are
 internal variables used by the implementation and should not be set manually.


@@ -109,10 +142,16 @@ Or to be more compatible you can use the following which should work in any
 Bourne shell:
 
     esc=`printf '\033'`
 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
 
     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 a
+symbolic-link to `tset` on some systems, adapt as necessary:
+
+    COLORED_STDERR_IGNORED_BINARIES=/usr/bin/tset
+    export COLORED_STDERR_IGNORED_BINARIES
+

 
 DEBUG
 -----
 
 DEBUG
 -----


@@ -139,9 +178,15 @@ warnings are appended at the end.
 KNOWN ISSUES
 ------------
 
 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.
   inlines the code into the program without calling any function.

+- 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
 
 
 BUGS


@@ -162,7 +207,7 @@ LICENSE
 
 coloredstderr is licensed under GPL version 3 or later.
 
 
 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
 
 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