15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Copyright 1994, 1995, 1996, 1999, 2000, 2001, 2002 Free Software 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Foundation, Inc. 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) This file is free documentation; the Free Software Foundation gives 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)unlimited permission to copy, distribute and modify it. 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Perftools-Specific Install Notes 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)================================ 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*** NOTE FOR 64-BIT LINUX SYSTEMS 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The glibc built-in stack-unwinder on 64-bit systems has some problems 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)with the perftools libraries. (In particular, the cpu/heap profiler 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)may be in the middle of malloc, holding some malloc-related locks when 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)they invoke the stack unwinder. The built-in stack unwinder may call 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)malloc recursively, which may require the thread to acquire a lock it 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)already holds: deadlock.) 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)For that reason, if you use a 64-bit system, we strongly recommend you 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)install libunwind before trying to configure or install gperftools. 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)libunwind can be found at 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) http://download.savannah.gnu.org/releases/libunwind/libunwind-0.99-beta.tar.gz 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Even if you already have libunwind installed, you should check the 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)version. Versions older than this will not work properly; too-new 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)versions introduce new code that does not work well with perftools 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)(because libunwind can call malloc, which will lead to deadlock). 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)There have been reports of crashes with libunwind 0.99 (see 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)http://code.google.com/p/gperftools/issues/detail?id=374). 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Alternately, you can use a more recent libunwind (e.g. 1.0.1) at the 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)cost of adding a bit of boilerplate to your code. For details, see 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)http://groups.google.com/group/google-perftools/msg/2686d9f24ac4365f 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) CAUTION: if you install libunwind from the url above, be aware that 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) you may have trouble if you try to statically link your binary with 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) perftools: that is, if you link with 'gcc -static -lgcc_eh ...'. 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) This is because both libunwind and libgcc implement the same C++ 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) exception handling APIs, but they implement them differently on 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) some platforms. This is not likely to be a problem on ia64, but 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) may be on x86-64. 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Also, if you link binaries statically, make sure that you add 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) -Wl,--eh-frame-hdr to your linker options. This is required so that 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) libunwind can find the information generated by the compiler 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) required for stack unwinding. 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Using -static is rare, though, so unless you know this will affect 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) you it probably won't. 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)If you cannot or do not wish to install libunwind, you can still try 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)to use the built-in stack unwinder. The built-in stack unwinder 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)requires that your application, the tcmalloc library, and system 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)libraries like libc, all be compiled with a frame pointer. This is 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*not* the default for x86-64. 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)If you are on x86-64 system, know that you have a set of system 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)libraries with frame-pointers enabled, and compile all your 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)applications with -fno-omit-frame-pointer, then you can enable the 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)built-in perftools stack unwinder by passing the 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)--enable-frame-pointers flag to configure. 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Even with the use of libunwind, there are still known problems with 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)stack unwinding on 64-bit systems, particularly x86-64. See the 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)"64-BIT ISSUES" section in README. 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)If you encounter problems, try compiling perftools with './configure 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)--enable-frame-pointers'. Note you will need to compile your 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)application with frame pointers (via 'gcc -fno-omit-frame-pointer 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)...') in this case. 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*** TCMALLOC LARGE PAGES: TRADING TIME FOR SPACE 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)You can set a compiler directive that makes tcmalloc faster, at the 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)cost of using more space (due to internal fragmentation). 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Internally, tcmalloc divides its memory into "pages." The default 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)page size is chosen to minimize memory use by reducing fragmentation. 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The cost is that keeping track of these pages can cost tcmalloc time. 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)We've added a new, experimental flag to tcmalloc that enables a larger 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)page size. In general, this will increase the memory needs of 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)applications using tcmalloc. However, in many cases it will speed up 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)the applications as well, particularly if they allocate and free a lot 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)of memory. We've seen average speedups of 3-5% on Google 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)applications. 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)This feature is still very experimental; it's not even a configure 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)flag yet. To build libtcmalloc with large pages, run 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure <normal flags> CXXFLAGS=-DTCMALLOC_LARGE_PAGES 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)(or add -DTCMALLOC_LARGE_PAGES to your existing CXXFLAGS argument). 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*** SMALL TCMALLOC CACHES: TRADING SPACE FOR TIME 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)You can set a compiler directive that makes tcmalloc use less memory 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)for overhead, at the cost of some time. 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Internally, tcmalloc keeps information about some of its internal data 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)structures in a cache. This speeds memory operations that need to 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)access this internal data. We've added a new, experimental flag to 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)tcmalloc that reduces the size of this cache, decresaing the memory 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)needs of applications using tcmalloc. 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)This feature is still very experimental; it's not even a configure 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)flag yet. To build libtcmalloc with smaller internal caches, run 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure <normal flags> CXXFLAGS=-DTCMALLOC_SMALL_BUT_SLOW 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)(or add -DTCMALLOC_SMALL_BUT_SLOW to your existing CXXFLAGS argument). 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*** NOTE FOR ___tls_get_addr ERROR 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)When compiling perftools on some old systems, like RedHat 8, you may 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)get an error like this: 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ___tls_get_addr: symbol not found 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)This means that you have a system where some parts are updated enough 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)to support Thread Local Storage, but others are not. The perftools 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)configure script can't always detect this kind of case, leading to 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)that error. To fix it, just comment out the line 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) #define HAVE_TLS 1 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)in your config.h file before building. 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*** TCMALLOC AND DLOPEN 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)To improve performance, we use the "initial exec" model of Thread 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Local Storage in tcmalloc. The price for this is the library will not 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)work correctly if it is loaded via dlopen(). This should not be a 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)problem, since loading a malloc-replacement library via dlopen is 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)asking for trouble in any case: some data will be allocated with one 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)malloc, some with another. If, for some reason, you *do* need to use 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)dlopen on tcmalloc, the easiest way is to use a version of tcmalloc 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)with TLS turned off; see the ___tls_get_addr note above. 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*** COMPILING ON NON-LINUX SYSTEMS 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Perftools has been tested on the following systems: 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FreeBSD 6.0 (x86) 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FreeBSD 8.1 (x86_64) 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux CentOS 5.5 (x86_64) 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Debian 4.0 (PPC) 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Debian 5.0 (x86) 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Fedora Core 3 (x86) 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Fedora Core 4 (x86) 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Fedora Core 5 (x86) 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Fedora Core 6 (x86) 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Fedora Core 13 (x86_64) 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Fedora Core 14 (x86_64) 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux RedHat 9 (x86) 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Slackware 13 (x86_64) 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Ubuntu 6.06.1 (x86) 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Ubuntu 6.06.1 (x86_64) 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Ubuntu 10.04 (x86) 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux Ubuntu 10.10 (x86_64) 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Mac OS X 10.3.9 (Panther) (PowerPC) 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Mac OS X 10.4.8 (Tiger) (PowerPC) 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Mac OS X 10.4.8 (Tiger) (x86) 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Mac OS X 10.5 (Leopard) (x86) 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Mac OS X 10.6 (Snow Leopard) (x86) 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Solaris 10 (x86_64) 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Windows XP, Visual Studio 2003 (VC++ 7.1) (x86) 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Windows XP, Visual Studio 2005 (VC++ 8) (x86) 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Windows XP, Visual Studio 2005 (VC++ 9) (x86) 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Windows XP, Visual Studio 2005 (VC++ 10) (x86) 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Windows XP, MinGW 5.1.3 (x86) 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Windows XP, Cygwin 5.1 (x86) 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)It works in its full generality on the Linux systems 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)tested (though see 64-bit notes above). Portions of perftools work on 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)the other systems. The basic memory-allocation library, 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)tcmalloc_minimal, works on all systems. The cpu-profiler also works 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)fairly widely. However, the heap-profiler and heap-checker are not 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)yet as widely supported. In general, the 'configure' script will 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)detect what OS you are building for, and only build the components 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)that work on that OS. 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Note that tcmalloc_minimal is perfectly usable as a malloc/new 1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)replacement, so it is possible to use tcmalloc on all the systems 1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)above, by linking in libtcmalloc_minimal. 1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FreeBSD: 1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) The following binaries build and run successfully (creating 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) libtcmalloc_minimal.so and libprofile.so in the process): 1935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) % ./configure 1945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) % make tcmalloc_minimal_unittest tcmalloc_minimal_large_unittest \ 1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) addressmap_unittest atomicops_unittest frag_unittest \ 1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) low_level_alloc_unittest markidle_unittest memalign_unittest \ 1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) packed_cache_test stacktrace_unittest system_alloc_unittest \ 1985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) thread_dealloc_unittest profiler_unittest.sh 1995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) % ./tcmalloc_minimal_unittest # to run this test 2005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) % [etc] # to run other tests 2015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Three caveats: first, frag_unittest tries to allocate 400M of memory, 2035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) and if you have less virtual memory on your system, the test may 2045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) fail with a bad_alloc exception. 2055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Second, profiler_unittest.sh sometimes fails in the "fork" test. 2075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) This is because stray SIGPROF signals from the parent process are 2085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) making their way into the child process. (This may be a kernel 2095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bug that only exists in older kernels.) The profiling code itself 2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) is working fine. This only affects programs that call fork(); for 2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) most programs, the cpu profiler is entirely safe to use. 2125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Third, perftools depends on /proc to get shared library 2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) information. If you are running a FreeBSD system without proc, 2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) perftools will not be able to map addresses to functions. Some 2165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) unittests will fail as a result. 2175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Finally, the new test introduced in perftools-1.2, 2195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) profile_handler_unittest, fails on FreeBSD. It has something to do 2205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) with how the itimer works. The cpu profiler test passes, so I 2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) believe the functionality is correct and the issue is with the test 2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) somehow. If anybody is an expert on itimers and SIGPROF in 2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FreeBSD, and would like to debug this, I'd be glad to hear the 2245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) results! 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) libtcmalloc.so successfully builds, and the "advanced" tcmalloc 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) functionality all works except for the leak-checker, which has 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Linux-specific code: 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) % make heap-profiler_unittest.sh maybe_threads_unittest.sh \ 2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) tcmalloc_unittest tcmalloc_both_unittest \ 2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) tcmalloc_large_unittest # THESE WORK 2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) % make -k heap-checker_unittest.sh \ 2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) heap-checker-death_unittest.sh # THESE DO NOT 2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Note that unless you specify --enable-heap-checker explicitly, 2365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 'make' will not build the heap-checker unittests on a FreeBSD 2375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) system. 2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) I have not tested other *BSD systems, but they are probably similar. 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Mac OS X: 2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) I've tested OS X 10.5 [Leopard], OS X 10.4 [Tiger] and OS X 10.3 2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [Panther] on both intel (x86) and PowerPC systems. For Panther 2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) systems, perftools does not work at all: it depends on a header 2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) file, OSAtomic.h, which is new in 10.4. (It's possible to get the 2475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) code working for Panther/i386 without too much work; if you're 2485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) interested in exploring this, drop an e-mail.) 2495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) For the other seven systems, the binaries and libraries that 2515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) successfully build are exactly the same as for FreeBSD. See that 2525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) section for a list of binaries and instructions on building them. 2535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) In addition, it appears OS X regularly fails profiler_unittest.sh 2555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) in the "thread" test (in addition to occassionally failing in the 2565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) "fork" test). It looks like OS X often delivers the profiling 2575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) signal to the main thread, even when it's sleeping, rather than 2585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) spawned threads that are doing actual work. If anyone knows 2595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) details of how OS X handles SIGPROF (via setitimer()) events with 2605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) threads, and has insight into this problem, please send mail to 2615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) google-perftools@googlegroups.com. 2625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Solaris 10 x86: 2645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) I've only tested using the GNU C++ compiler, not the Sun C++ 2665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) compiler. Using g++ requires setting the PATH appropriately when 2675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) configuring. 2685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) % PATH=${PATH}:/usr/sfw/bin/:/usr/ccs/bin ./configure 2705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) % PATH=${PATH}:/usr/sfw/bin/:/usr/ccs/bin make [...] 2715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Again, the binaries and libraries that successfully build are 2735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) exactly the same as for FreeBSD. (However, while libprofiler.so can 2745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) be used to generate profiles, pprof is not very successful at 2755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) reading them -- necessary helper programs like nm don't seem 2765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) to be installed by default on Solaris, or perhaps are only 2775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) installed as part of the Sun C++ compiler package.) See that 2785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) section for a list of binaries, and instructions on building them. 2795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Windows (MSVC, Cygwin, and MinGW): 2815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Work on Windows is rather preliminary: we haven't found a good way 2835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) to get stack traces in release mode on windows (that is, when FPO 2845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) is enabled), so the heap profiling may not be reliable in that 2855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) case. Also, heap-checking and CPU profiling do not yet work at 2865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) all. But as in other ports, the basic tcmalloc library 2875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) functionality, overriding malloc and new and such (and even 2885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) windows-specific functions like _aligned_malloc!), is working fine, 2895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) at least with VC++ 7.1 (Visual Studio 2003) through VC++ 10.0, 2905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) in both debug and release modes. See README.windows for 2915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) instructions on how to install on Windows using Visual Studio. 2925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Cygwin can compile some but not all of perftools. Furthermore, 2945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) there is a problem with exception-unwinding in cygwin (it can call 2955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) malloc, which can call the exception-unwinding-setup code, which 2965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) can lead to an infinite loop). I've comitted a workaround to the 2975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) exception unwinding problem, but it only works in debug mode and 2985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) when statically linking in tcmalloc. I hope to have a more proper 2995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) fix in a later release. To configure under cygwin, run 3005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure --disable-shared CXXFLAGS=-g && make 3025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Most of cygwin will compile (cygwin doesn't allow weak symbols, so 3045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) the heap-checker and a few other pieces of functionality will not 3055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) compile). 'make' will compile those libraries and tests that can 3065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) be compiled. You can run 'make check' to make sure the basic 3075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) functionality is working. I've heard reports that some versions of 3085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) cygwin fail calls to pthread_join() with EINVAL, causing several 3095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) tests to fail. If you have any insight into this, please mail 3105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) google-perftools@googlegroups.com. 3115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) This Windows functionality is also available using MinGW and Msys, 3135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) In this case, you can use the regular './configure && make' 3145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) process. 'make install' should also work. The Makefile will limit 3155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) itself to those libraries and binaries that work on windows. 3165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Basic Installation 3195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)================== 3205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) These are generic installation instructions. 3225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) The `configure' shell script attempts to guess correct values for 3245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)various system-dependent variables used during compilation. It uses 3255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)those values to create a `Makefile' in each directory of the package. 3265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)It may also create one or more `.h' files containing system-dependent 3275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)definitions. Finally, it creates a shell script `config.status' that 3285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)you can run in the future to recreate the current configuration, and a 3295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)file `config.log' containing compiler output (useful mainly for 3305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)debugging `configure'). 3315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) It can also use an optional file (typically called `config.cache' 3335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)and enabled with `--cache-file=config.cache' or simply `-C') that saves 3345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)the results of its tests to speed up reconfiguring. (Caching is 3355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)disabled by default to prevent problems with accidental use of stale 3365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)cache files.) 3375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If you need to do unusual things to compile the package, please try 3395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)to figure out how `configure' could check whether to do them, and mail 3405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)diffs or instructions to the address given in the `README' so they can 3415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)be considered for the next release. If you are using the cache, and at 3425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)some point `config.cache' contains results you don't want to keep, you 3435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)may remove or edit it. 3445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) The file `configure.ac' (or `configure.in') is used to create 3465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`configure' by a program called `autoconf'. You only need 3475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`configure.ac' if you want to change it or regenerate `configure' using 3485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)a newer version of `autoconf'. 3495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The simplest way to compile this package is: 3515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1. `cd' to the directory containing the package's source code and type 3535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) `./configure' to configure the package for your system. If you're 3545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) using `csh' on an old version of System V, you might need to type 3555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) `sh ./configure' instead to prevent `csh' from trying to execute 3565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) `configure' itself. 3575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Running `configure' takes awhile. While running, it prints some 3595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) messages telling which features it is checking for. 3605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2. Type `make' to compile the package. 3625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3. Optionally, type `make check' to run any self-tests that come with 3645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) the package. 3655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4. Type `make install' to install the programs and any data files and 3675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) documentation. 3685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5. You can remove the program binaries and object files from the 3705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) source code directory by typing `make clean'. To also remove the 3715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) files that `configure' created (so you can compile the package for 3725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) a different kind of computer), type `make distclean'. There is 3735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) also a `make maintainer-clean' target, but that is intended mainly 3745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) for the package's developers. If you use it, you may have to get 3755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) all sorts of other programs in order to regenerate files that came 3765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) with the distribution. 3775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Compilers and Options 3795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)===================== 3805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Some systems require unusual options for compilation or linking that 3825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)the `configure' script does not know about. Run `./configure --help' 3835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)for details on some of the pertinent environment variables. 3845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) You can give `configure' initial values for configuration parameters 3865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)by setting variables in the command line or in the environment. Here 3875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)is an example: 3885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix 3905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) *Note Defining Variables::, for more details. 3925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Compiling For Multiple Architectures 3945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)==================================== 3955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) You can compile the package for more than one kind of computer at the 3975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)same time, by placing the object files for each architecture in their 3985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)own directory. To do this, you must use a version of `make' that 3995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)supports the `VPATH' variable, such as GNU `make'. `cd' to the 4005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)directory where you want the object files and executables to go and run 4015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)the `configure' script. `configure' automatically checks for the 4025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)source code in the directory that `configure' is in and in `..'. 4035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If you have to use a `make' that does not support the `VPATH' 4055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)variable, you have to compile the package for one architecture at a 4065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)time in the source code directory. After you have installed the 4075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)package for one architecture, use `make distclean' before reconfiguring 4085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)for another architecture. 4095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Installation Names 4115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)================== 4125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) By default, `make install' will install the package's files in 4145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`/usr/local/bin', `/usr/local/man', etc. You can specify an 4155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)installation prefix other than `/usr/local' by giving `configure' the 4165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)option `--prefix=PATH'. 4175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) You can specify separate installation prefixes for 4195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)architecture-specific files and architecture-independent files. If you 4205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)give `configure' the option `--exec-prefix=PATH', the package will use 4215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)PATH as the prefix for installing programs and libraries. 4225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Documentation and other data files will still use the regular prefix. 4235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) In addition, if you use an unusual directory layout you can give 4255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)options like `--bindir=PATH' to specify different values for particular 4265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)kinds of files. Run `configure --help' for a list of the directories 4275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)you can set and what kinds of files go in them. 4285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If the package supports it, you can cause programs to be installed 4305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)with an extra prefix or suffix on their names by giving `configure' the 4315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. 4325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Optional Features 4345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)================= 4355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Some packages pay attention to `--enable-FEATURE' options to 4375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`configure', where FEATURE indicates an optional part of the package. 4385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)They may also pay attention to `--with-PACKAGE' options, where PACKAGE 4395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)is something like `gnu-as' or `x' (for the X Window System). The 4405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`README' should mention any `--enable-' and `--with-' options that the 4415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)package recognizes. 4425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) For packages that use the X Window System, `configure' can usually 4445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)find the X include and library files automatically, but if it doesn't, 4455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)you can use the `configure' options `--x-includes=DIR' and 4465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`--x-libraries=DIR' to specify their locations. 4475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Specifying the System Type 4495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)========================== 4505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) There may be some features `configure' cannot figure out 4525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)automatically, but needs to determine by the type of machine the package 4535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)will run on. Usually, assuming the package is built to be run on the 4545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)_same_ architectures, `configure' can figure that out, but if it prints 4555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)a message saying it cannot guess the machine type, give it the 4565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`--build=TYPE' option. TYPE can either be a short name for the system 4575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)type, such as `sun4', or a canonical name which has the form: 4585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) CPU-COMPANY-SYSTEM 4605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)where SYSTEM can have one of these forms: 4625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) OS KERNEL-OS 4645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) See the file `config.sub' for the possible values of each field. If 4665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`config.sub' isn't included in this package, then this package doesn't 4675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)need to know the machine type. 4685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If you are _building_ compiler tools for cross-compiling, you should 4705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)use the `--target=TYPE' option to select the type of system they will 4715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)produce code for. 4725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If you want to _use_ a cross compiler, that generates code for a 4745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)platform different from the build platform, you should specify the 4755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)"host" platform (i.e., that on which the generated programs will 4765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)eventually be run) with `--host=TYPE'. 4775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Sharing Defaults 4795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)================ 4805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If you want to set default values for `configure' scripts to share, 4825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)you can create a site shell script called `config.site' that gives 4835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)default values for variables like `CC', `cache_file', and `prefix'. 4845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`configure' looks for `PREFIX/share/config.site' if it exists, then 4855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`PREFIX/etc/config.site' if it exists. Or, you can set the 4865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`CONFIG_SITE' environment variable to the location of the site script. 4875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)A warning: not all `configure' scripts look for a site script. 4885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Defining Variables 4905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)================== 4915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Variables not defined in a site shell script can be set in the 4935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)environment passed to `configure'. However, some packages may run 4945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)configure again during the build, and the customized values of these 4955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)variables may be lost. In order to avoid this problem, you should set 4965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)them in the `configure' command line, using `VAR=value'. For example: 4975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure CC=/usr/local2/bin/gcc 4995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)will cause the specified gcc to be used as the C compiler (unless it is 5015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)overridden in the site shell script). 5025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`configure' Invocation 5045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)====================== 5055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) `configure' recognizes the following options to control how it 5075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)operates. 5085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`--help' 5105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`-h' 5115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Print a summary of the options to `configure', and exit. 5125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`--version' 5145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`-V' 5155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Print the version of Autoconf used to generate the `configure' 5165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) script, and exit. 5175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`--cache-file=FILE' 5195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Enable the cache: use and save the results of the tests in FILE, 5205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) traditionally `config.cache'. FILE defaults to `/dev/null' to 5215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) disable caching. 5225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`--config-cache' 5245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`-C' 5255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Alias for `--cache-file=config.cache'. 5265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`--quiet' 5285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`--silent' 5295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`-q' 5305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Do not print messages saying which checks are being made. To 5315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) suppress all normal output, redirect it to `/dev/null' (any error 5325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) messages will still be shown). 5335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`--srcdir=DIR' 5355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Look for the package's source code in directory DIR. Usually 5365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) `configure' can determine that directory automatically. 5375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`configure' also accepts some other, not widely useful, options. Run 5395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)`configure --help' for more details. 540