Debian Codegraph @

extra/gperftools/gperftools-2.15/INSTALL

raw
1 Copyright 1994, 1995, 1996, 1999, 2000, 2001, 2002 Free Software
2 Foundation, Inc.
3
4 This file is free documentation; the Free Software Foundation gives
5 unlimited permission to copy, distribute and modify it.
6
7
8 Perftools-Specific Install Notes
9 ================================
10
11 See generic autotool-provided installation notes at the
12 end. Immediately below you can see gperftools-specific details.
13
14 *** Building from source repository
15
16 As of 2.1 gperftools does not have configure and other autotools
17 products checked into it's source repository. This is common practice
18 for projects using autotools.
19
20 NOTE: Source releases (.tar.gz that you download from
21 https://github.com/gperftools/gperftools/releases) still have all
22 required files just as before. Nothing has changed w.r.t. building
23 from .tar.gz releases.
24
25 But, in order to build gperftools checked out from subversion
26 repository you need to have autoconf, automake and libtool
27 installed. And before running ./configure you have to generate it (and
28 a bunch of other files) by running ./autogen.sh script. That script
29 will take care of calling correct autotools programs in correct order.
30
31 If you're maintainer then it's business as usual too. Just run make
32 dist (or, preferably, make distcheck) and it'll produce .tar.gz or
33 .tar.bz2 with all autotools magic already included. So that users can
34 build our software without having autotools.
35
36
37 *** Stacktrace capturing details
38
39 A number of gperftools facilities capture stack traces. And
40 occasionally this happens in 'tricky' locations, like in SIGPROF
41 handler. So some platforms and library versions occasionally cause
42 troubles (crashes or hangs, or truncated stack traces).
43
44 So we do provide several implementations that our users are able to
45 select at runtime. Pass TCMALLOC_STACKTRACE_METHOD_VERBOSE=t as
46 environment variable to ./stacktrace_unittest to see options.
47
48 * frame-pointer-based stacktracing is fully supported on x86 (all 3
49 kinds: i386, x32 and x86-64 are suppored), aarch64 and riscv. But
50 all modern architectures and ABIs by default build code without
51 frame pointers (even on i386). So in order to get anything useful
52 out of this option, you need to build your code with frame
53 pointers. It adds some performance overhead (usually people quote
54 order of 2%-3%, but it can really vary based on workloads). Also it
55 is worth mentioning, that it is fairly common for various asm
56 routines not to have frame pointers, so you'll have somewhat
57 imperfect profiles out of typical asm bits like memcpy. This stack
58 trace capuring method is also fastest (like 2-3 orders of magnitude
59 faster), which will matter when stacktrace capturing is done a lot
60 (e.g. heap profiler).
61
62 * libgcc-based stacktracing works particularly great on modern
63 GNU/Linux systems with glibc 2.34 or later and libgcc from gcc 12 or
64 later. Thanks to usage of dl_find_object API introduced in recent
65 glibc-s this implementation seems to be truly async-signal safe and
66 it is reasonably fast too. On Linux and other ELF platforms it uses
67 eh_frame facility (which is very similar to dwarf unwind info). It
68 was originally introduced for exception handling. On most modern
69 platforms this unwind info is automatically added by compilers. On
70 others you might need to add -fexceptions and/or
71 -fasynchrnous-unwind-tables to your compiler flags. To make this
72 option default, pass --enable-libgcc-unwinder-by-default to
73 configure. When used without dl_find_object it will occasionally
74 deadlock especially when used in cpuprofiler.
75
76 * libunwind is another supported mechanism and is default when
77 available. It also depends on eh_frame stuff (or dwarf or some
78 arm-specific thingy when available). When using it, be sure to use
79 latest available libunwind version. As with libgcc some people
80 occasionally had trouble with it on codes with broken or missing
81 unwind info. If you encounter something like that, first make sure
82 to file tickets against your compiler vender. Second, libunwind has
83 configure option to check accesses more thoroughly, so consider
84 that.
85
86 * many systems provide backtrace() function either as part of their
87 libc or in -lexecinfo. On most systems, including GNU/Linux, it is
88 not built by default, so pass --enable-stacktrace-via-backtrace to
89 configure to enable it. Occasionally this implementation will call
90 malloc when capturing backtrace, but we should automagically handle
91 it via our "emergency malloc" facility which is now built by default
92 on most systems (but it currently doesn't handle being used by
93 cpuprofiler).
94
95
96 *** TCMALLOC LARGE PAGES: TRADING TIME FOR SPACE
97
98 You can set a compiler directive that makes tcmalloc faster, at the
99 cost of using more space (due to internal fragmentation).
100
101 Internally, tcmalloc divides its memory into "pages." The default
102 page size is chosen to minimize memory use by reducing fragmentation.
103 The cost is that keeping track of these pages can cost tcmalloc time.
104 We've added a new flag to tcmalloc that enables a larger page size.
105 In general, this will increase the memory needs of applications using
106 tcmalloc. However, in many cases it will speed up the applications
107 as well, particularly if they allocate and free a lot of memory. We've
108 seen average speedups of 3-5% on Google applications.
109
110 To build libtcmalloc with large pages you need to use the
111 --with-tcmalloc-pagesize=ARG configure flag, e.g.:
112
113 ./configure <other flags> --with-tcmalloc-pagesize=32
114
115 The ARG argument can be 4, 8, 16, 32, 64, 128 or 256 which sets the
116 internal page size to 4K, 8K, 16K, 32K, 64K, 128K and 256K respectively.
117 The default is 8K.
118
119
120 *** SMALL TCMALLOC CACHES: TRADING SPACE FOR TIME
121
122 You can set a compiler directive that makes tcmalloc use less memory
123 for overhead, at the cost of some time.
124
125 Internally, tcmalloc keeps information about some of its internal data
126 structures in a cache. This speeds memory operations that need to
127 access this internal data. We've added a new, experimental flag to
128 tcmalloc that reduces the size of this cache, decresaing the memory
129 needs of applications using tcmalloc.
130
131 This feature is still very experimental; it's not even a configure
132 flag yet. To build libtcmalloc with smaller internal caches, run
133
134 ./configure <normal flags> CXXFLAGS=-DTCMALLOC_SMALL_BUT_SLOW
135
136 (or add -DTCMALLOC_SMALL_BUT_SLOW to your existing CXXFLAGS argument).
137
138
139 *** TCMALLOC AND DLOPEN
140
141 To improve performance, we use the "initial exec" model of Thread
142 Local Storage in tcmalloc. The price for this is the library will not
143 work correctly if it is loaded via dlopen(). This should not be a
144 problem, since loading a malloc-replacement library via dlopen is
145 asking for trouble in any case: some data will be allocated with one
146 malloc, some with another.
147
148
149 *** COMPILING ON NON-LINUX SYSTEMS
150
151 We regularly build and test on typical modern GNU/Linux systems. You
152 should expect all tests to pass on modern Linux distros and x86,
153 aarch64 and riscv machines. Other machine types may fail some tests,
154 but you should expect at least malloc to be fully functional.
155
156 Perftools has been tested on the following non-Linux systems:
157 Various recent versions of FreeBSD (x86-64 mostly)
158 Recent version of NetBSD (x86-64)
159 Recent versions of OSX (aarch64, x86 and ppc hasn't been tested for some time)
160 Solaris 10 (x86_64), but not recently
161 Windows using both MSVC (starting from MSVC 2015 and later) and mingw toolchains
162 Windows XP and other obsolete versions have not been tested recently
163 Windows XP, Cygwin 5.1 (x86), but not recently
164
165 Portions of gperftools work on those other systems. The basic
166 memory-allocation library, tcmalloc_minimal, works on all systems.
167 The cpu-profiler also works fairly widely. However, the heap-profiler
168 and heap-checker are not yet as widely supported. Heap checker is now
169 deprecated. In general, the 'configure' script will detect what OS you
170 are building for, and only build the components that work on that OS.
171
172 Note that tcmalloc_minimal is perfectly usable as a malloc/new
173 replacement, so it is possible to use tcmalloc on all the systems
174 above, by linking in libtcmalloc_minimal.
175
176 ** Solaris 10 x86: (note, this is fairly old)
177
178 I've only tested using the GNU C++ compiler, not the Sun C++
179 compiler. Using g++ requires setting the PATH appropriately when
180 configuring.
181
182 % PATH=${PATH}:/usr/sfw/bin/:/usr/ccs/bin ./configure
183 % PATH=${PATH}:/usr/sfw/bin/:/usr/ccs/bin make [...]
184
185 Again, the binaries and libraries that successfully build are
186 exactly the same as for FreeBSD. (However, while libprofiler.so can
187 be used to generate profiles, pprof is not very successful at
188 reading them -- necessary helper programs like nm don't seem
189 to be installed by default on Solaris, or perhaps are only
190 installed as part of the Sun C++ compiler package.) See that
191 section for a list of binaries, and instructions on building them.
192
193 ** Windows (MSVC, Cygwin, and MinGW):
194
195 Work on Windows is rather preliminary: only tcmalloc_minimal is
196 supported.
197
198 This Windows functionality is also available using MinGW and Msys,
199 In this case, you can use the regular './configure && make'
200 process. 'make install' should also work. The Makefile will limit
201 itself to those libraries and binaries that work on windows.
202
203 ** AIX (as of 2021)
204
205 I've tested using the IBM XL and IBM Open XL Compilers. The
206 minimum requirement for IBM XL is V16 which includes C++11
207 support. IBM XL and gcc are not ABI compatible. If you would
208 like to use the library with a gcc built executable then the
209 library must also be built with gcc. To use the library with
210 and IBM XL built binary then it follows that the library must
211 also be built with IBM XL.
212
213 Both 32-bit and 64-bit builds have been tested.
214
215 To do a 32-bit IBM XL build:
216 % ./configure CC="xlclang" CXX="xlclang++" AR="ar"
217 RANLIB="ranlib" NM="nm"
218 To do a 64-bit IBM XL build:
219 % ./configure CC="xlclang -q64" CXX="xlclang++ -q64"
220 AR="ar -X64" RANLIB="ranlib -X64" NM="nm -X64"
221
222 Add your favorite optimization levels via CFLAGS and CXXFLAGS.
223
224 If you link to the shared library but it may not work as you
225 expect. Allocations and deallocations that occur from within
226 the Standard C and C++ libraries will not be redirected the
227 tcmalloc library.
228
229 The recommended method is to use the AIX User-defined malloc
230 replacement as documented by IBM. This replaces the default
231 AIX memory subsystem with a user defined memory subsystem.
232
233 The AIX user defined memory subsystem specifies that the 32-
234 and 64- bit objects must be placed in an archive with the
235 32-bit shared object named mem32.o and the 64-bit shared
236 object named mem64.o.
237
238 It is recommended to make combined 32_64 bit archive by
239 doing a 64-bit build, then copy the shared library to mem64.o
240 add mem64.o the archive, then do a 32-bit build
241 copy the shared library to mem32.o and add it to the same
242 combined archive.
243
244 For eg) perform a 64-bit build then:
245 % cp libtcmalloc_minimal.so.4 mem64.o
246 % ar -X32_64 -r libtmalloc_minimal.a mem64.o
247
248 Followed by a 32-bit build:
249 % cp libtcmalloc_minimal.so.4 mem32.o
250 % ar -X32_64 -r libtmalloc_minimal.a mem32.o
251
252 The final archive should contain both mem32.o and mem64.o
253
254 To use the library you are expected have the library location
255 in your LIBPATH or LD_LIBRARY_PATH followed by exporting the
256 environment variable MALLOCTYPE=user:libtcmalloc_minimal.a to
257 enable the new user defined memory subsystem.
258
259 I recommend using:
260 % MALLOCTYPE=user:libtcmalloc_minimal.a <user-exectuable>
261 to minimize the impact of replacing the memory subsystem. Once
262 the subsystem is replaced it is used for all commands issued from
263 the terminal.
264
265
266 Basic Installation
267 ==================
268
269 These are generic installation instructions.
270
271 The `configure' shell script attempts to guess correct values for
272 various system-dependent variables used during compilation. It uses
273 those values to create a `Makefile' in each directory of the package.
274 It may also create one or more `.h' files containing system-dependent
275 definitions. Finally, it creates a shell script `config.status' that
276 you can run in the future to recreate the current configuration, and a
277 file `config.log' containing compiler output (useful mainly for
278 debugging `configure').
279
280 It can also use an optional file (typically called `config.cache'
281 and enabled with `--cache-file=config.cache' or simply `-C') that saves
282 the results of its tests to speed up reconfiguring. (Caching is
283 disabled by default to prevent problems with accidental use of stale
284 cache files.)
285
286 If you need to do unusual things to compile the package, please try
287 to figure out how `configure' could check whether to do them, and mail
288 diffs or instructions to the address given in the `README' so they can
289 be considered for the next release. If you are using the cache, and at
290 some point `config.cache' contains results you don't want to keep, you
291 may remove or edit it.
292
293 The file `configure.ac' (or `configure.in') is used to create
294 `configure' by a program called `autoconf'. You only need
295 `configure.ac' if you want to change it or regenerate `configure' using
296 a newer version of `autoconf'.
297
298 The simplest way to compile this package is:
299
300 1. `cd' to the directory containing the package's source code and type
301 `./configure' to configure the package for your system. If you're
302 using `csh' on an old version of System V, you might need to type
303 `sh ./configure' instead to prevent `csh' from trying to execute
304 `configure' itself.
305
306 Running `configure' takes awhile. While running, it prints some
307 messages telling which features it is checking for.
308
309 2. Type `make' to compile the package.
310
311 3. Optionally, type `make check' to run any self-tests that come with
312 the package.
313
314 4. Type `make install' to install the programs and any data files and
315 documentation.
316
317 5. You can remove the program binaries and object files from the
318 source code directory by typing `make clean'. To also remove the
319 files that `configure' created (so you can compile the package for
320 a different kind of computer), type `make distclean'. There is
321 also a `make maintainer-clean' target, but that is intended mainly
322 for the package's developers. If you use it, you may have to get
323 all sorts of other programs in order to regenerate files that came
324 with the distribution.
325
326 Compilers and Options
327 =====================
328
329 Some systems require unusual options for compilation or linking that
330 the `configure' script does not know about. Run `./configure --help'
331 for details on some of the pertinent environment variables.
332
333 You can give `configure' initial values for configuration parameters
334 by setting variables in the command line or in the environment. Here
335 is an example:
336
337 ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
338
339 *Note Defining Variables::, for more details.
340
341 Compiling For Multiple Architectures
342 ====================================
343
344 You can compile the package for more than one kind of computer at the
345 same time, by placing the object files for each architecture in their
346 own directory. To do this, you must use a version of `make' that
347 supports the `VPATH' variable, such as GNU `make'. `cd' to the
348 directory where you want the object files and executables to go and run
349 the `configure' script. `configure' automatically checks for the
350 source code in the directory that `configure' is in and in `..'.
351
352 If you have to use a `make' that does not support the `VPATH'
353 variable, you have to compile the package for one architecture at a
354 time in the source code directory. After you have installed the
355 package for one architecture, use `make distclean' before reconfiguring
356 for another architecture.
357
358 Installation Names
359 ==================
360
361 By default, `make install' will install the package's files in
362 `/usr/local/bin', `/usr/local/man', etc. You can specify an
363 installation prefix other than `/usr/local' by giving `configure' the
364 option `--prefix=PATH'.
365
366 You can specify separate installation prefixes for
367 architecture-specific files and architecture-independent files. If you
368 give `configure' the option `--exec-prefix=PATH', the package will use
369 PATH as the prefix for installing programs and libraries.
370 Documentation and other data files will still use the regular prefix.
371
372 In addition, if you use an unusual directory layout you can give
373 options like `--bindir=PATH' to specify different values for particular
374 kinds of files. Run `configure --help' for a list of the directories
375 you can set and what kinds of files go in them.
376
377 If the package supports it, you can cause programs to be installed
378 with an extra prefix or suffix on their names by giving `configure' the
379 option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
380
381 Optional Features
382 =================
383
384 Some packages pay attention to `--enable-FEATURE' options to
385 `configure', where FEATURE indicates an optional part of the package.
386 They may also pay attention to `--with-PACKAGE' options, where PACKAGE
387 is something like `gnu-as' or `x' (for the X Window System). The
388 `README' should mention any `--enable-' and `--with-' options that the
389 package recognizes.
390
391 For packages that use the X Window System, `configure' can usually
392 find the X include and library files automatically, but if it doesn't,
393 you can use the `configure' options `--x-includes=DIR' and
394 `--x-libraries=DIR' to specify their locations.
395
396 Specifying the System Type
397 ==========================
398
399 There may be some features `configure' cannot figure out
400 automatically, but needs to determine by the type of machine the package
401 will run on. Usually, assuming the package is built to be run on the
402 _same_ architectures, `configure' can figure that out, but if it prints
403 a message saying it cannot guess the machine type, give it the
404 `--build=TYPE' option. TYPE can either be a short name for the system
405 type, such as `sun4', or a canonical name which has the form:
406
407 CPU-COMPANY-SYSTEM
408
409 where SYSTEM can have one of these forms:
410
411 OS KERNEL-OS
412
413 See the file `config.sub' for the possible values of each field. If
414 `config.sub' isn't included in this package, then this package doesn't
415 need to know the machine type.
416
417 If you are _building_ compiler tools for cross-compiling, you should
418 use the `--target=TYPE' option to select the type of system they will
419 produce code for.
420
421 If you want to _use_ a cross compiler, that generates code for a
422 platform different from the build platform, you should specify the
423 "host" platform (i.e., that on which the generated programs will
424 eventually be run) with `--host=TYPE'.
425
426 Sharing Defaults
427 ================
428
429 If you want to set default values for `configure' scripts to share,
430 you can create a site shell script called `config.site' that gives
431 default values for variables like `CC', `cache_file', and `prefix'.
432 `configure' looks for `PREFIX/share/config.site' if it exists, then
433 `PREFIX/etc/config.site' if it exists. Or, you can set the
434 `CONFIG_SITE' environment variable to the location of the site script.
435 A warning: not all `configure' scripts look for a site script.
436
437 Defining Variables
438 ==================
439
440 Variables not defined in a site shell script can be set in the
441 environment passed to `configure'. However, some packages may run
442 configure again during the build, and the customized values of these
443 variables may be lost. In order to avoid this problem, you should set
444 them in the `configure' command line, using `VAR=value'. For example:
445
446 ./configure CC=/usr/local2/bin/gcc
447
448 will cause the specified gcc to be used as the C compiler (unless it is
449 overridden in the site shell script).
450
451 `configure' Invocation
452 ======================
453
454 `configure' recognizes the following options to control how it
455 operates.
456
457 `--help'
458 `-h'
459 Print a summary of the options to `configure', and exit.
460
461 `--version'
462 `-V'
463 Print the version of Autoconf used to generate the `configure'
464 script, and exit.
465
466 `--cache-file=FILE'
467 Enable the cache: use and save the results of the tests in FILE,
468 traditionally `config.cache'. FILE defaults to `/dev/null' to
469 disable caching.
470
471 `--config-cache'
472 `-C'
473 Alias for `--cache-file=config.cache'.
474
475 `--quiet'
476 `--silent'
477 `-q'
478 Do not print messages saying which checks are being made. To
479 suppress all normal output, redirect it to `/dev/null' (any error
480 messages will still be shown).
481
482 `--srcdir=DIR'
483 Look for the package's source code in directory DIR. Usually
484 `configure' can determine that directory automatically.
485
486 `configure' also accepts some other, not widely useful, options. Run
487 `configure --help' for more details.