hookmacros.h: Reduce duplication in macros.

[coloredstderr/coloredstderr.git] / README

diff --git a/README b/README
index e00fdfaf2be4186fa4cafdabed62511049ecf06c..298ce4ff3c6346ce373afcf2bb421fc77dd588ea 100644 (file)
--- a/README
+++ b/README
@@ -31,6 +31,32 @@ DEPENDENCIES
 - dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's ld.so)
 
 
+INSTALLATION
+------------
+
+    ./configure && make && make check
+
+Then either install the library with `make install` or just copy it from
+`src/.libs/` to wherever you want to install it:
+
+    rm -f /destination/path/for/library/libcoloredstderr.so
+    cp -L src/.libs/libcoloredstderr.so /destination/path/for/library/
+
+*Important:* If you install `libcoloredstderr.so` manually, make sure _not_ to
+use plain `cp` to overwrite an existing `libcoloredstderr.so` file which is in
+use! Doing so will crash all processes which were started with 'LD_PRELOAD'
+set to this file. This is not a bug in coloredstderr, but a general problem.
+`cp` truncates the file which causes the `mmap()` ed library to be in an
+inconsistent state causing a segmentation fault when using any functions of
+the library. Just remove the file first and then copy it. `make install`
+handles the install in this way and is therefore not affected.
+
+As a simple safeguard, `make` builds and installs the `libcoloredstderr.so`
+file non-writable to prevent accidental overwrites. Even if the overwrite is
+forced with `cp -f`, the file is unlinked and recreated by `cp` because the
+file is non-writable, preventing the problem.
+
+
 USAGE
 -----
 
@@ -68,13 +94,32 @@ The following additional environment variables are available:
   are colored.
 
 
+To set custom colors as pre/post strings you can use the `$''` feature of Bash
+and Zsh:
+
+    export COLORED_STDERR_PRE=$'\033[91m' # bright red
+    export COLORED_STDERR_POST=$'\033[0m' # default
+
+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_POST="${esc}[0m" # default
+    export COLORED_STDERR_PRE COLORED_STDERR_POST
+
+
 DEBUG
 -----
 
 To enable debug mode, configure coloredstderr with '--enable-debug'.
 
+*Important:* Debug mode enables `assert()`s in the code which might abort the
+process if an error condition is detected!
+
 Debug mode is slower than normal mode. To log only warnings without the
-overhead of debug mode use '--enable-warnings'.
+overhead of debug mode use '--enable-warnings'. `assert()`s are not enabled
+with '--enable-warnings', so it's safe to use.
 
 Debug messages are written to the file `colored_stderr_debug_log.txt` in the
 current working directory _if_ it exists. If it exists debug messages are