diff --git a/INSTALL b/INSTALL index d3c5b40..0babe24 100644 --- a/INSTALL +++ b/INSTALL @@ -7,6 +7,66 @@ Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005, This file is free documentation; the Free Software Foundation gives unlimited permission to copy, distribute and modify it. +Glog-Specific Install Notes +================================ + +*** NOTE FOR 64-BIT LINUX SYSTEMS + +The glibc built-in stack-unwinder on 64-bit systems has some problems +with the glog libraries. (In particular, if you are using +InstallFailureSignalHandler(), the signal may be raised in the middle +of malloc, holding some malloc-related locks when they invoke the +stack unwinder. The built-in stack unwinder may call malloc +recursively, which may require the thread to acquire a lock it already +holds: deadlock.) + +For that reason, if you use a 64-bit system and you need +InstallFailureSignalHandler(), we strongly recommend you install +libunwind before trying to configure or install google glog. +libunwind can be found at + + http://download.savannah.nongnu.org/releases/libunwind/libunwind-snap-070410.tar.gz + +Even if you already have libunwind installed, you will probably still +need to install from the snapshot to get the latest version. + +CAUTION: if you install libunwind from the URL above, be aware that +you may have trouble if you try to statically link your binary with +glog: that is, if you link with 'gcc -static -lgcc_eh ...'. This +is because both libunwind and libgcc implement the same C++ exception +handling APIs, but they implement them differently on some platforms. +This is not likely to be a problem on ia64, but may be on x86-64. + +Also, if you link binaries statically, make sure that you add +-Wl,--eh-frame-hdr to your linker options. This is required so that +libunwind can find the information generated by the compiler required +for stack unwinding. + +Using -static is rare, though, so unless you know this will affect you +it probably won't. + +If you cannot or do not wish to install libunwind, you can still try +to use two kinds of stack-unwinder: 1. glibc built-in stack-unwinder +and 2. frame pointer based stack-unwinder. + +1. As we already mentioned, glibc's unwinder has a deadlock issue. +However, if you don't use InstallFailureSignalHandler() or you don't +worry about the rare possibilities of deadlocks, you can use this +stack-unwinder. If you specify no options and libunwind isn't +detected on your system, the configure script chooses this unwinder by +default. + +2. The frame pointer based stack unwinder requires that your +application, the glog library, and system libraries like libc, all be +compiled with a frame pointer. This is *not* the default for x86-64. + +If you are on x86-64 system, know that you have a set of system +libraries with frame-pointers enabled, and compile all your +applications with -fno-omit-frame-pointer, then you can enable the +frame pointer based stack unwinder by passing the +--enable-frame-pointers flag to configure. + + Basic Installation ==================