The Tor Browser / file comparison
comparison: memory/jemalloc/src/INSTALL
memory/jemalloc/src/INSTALL
- changeset 0
- 6474c204b198
equal
deleted
inserted
replaced
| -1:000000000000 | 0:e54a32e8d831 |
|---|---|
| 1 Building and installing jemalloc can be as simple as typing the following while | |
| 2 in the root directory of the source tree: | |
| 3 | |
| 4 ./configure | |
| 5 make | |
| 6 make install | |
| 7 | |
| 8 === Advanced configuration ===================================================== | |
| 9 | |
| 10 The 'configure' script supports numerous options that allow control of which | |
| 11 functionality is enabled, where jemalloc is installed, etc. Optionally, pass | |
| 12 any of the following arguments (not a definitive list) to 'configure': | |
| 13 | |
| 14 --help | |
| 15 Print a definitive list of options. | |
| 16 | |
| 17 --prefix=<install-root-dir> | |
| 18 Set the base directory in which to install. For example: | |
| 19 | |
| 20 ./configure --prefix=/usr/local | |
| 21 | |
| 22 will cause files to be installed into /usr/local/include, /usr/local/lib, | |
| 23 and /usr/local/man. | |
| 24 | |
| 25 --with-rpath=<colon-separated-rpath> | |
| 26 Embed one or more library paths, so that libjemalloc can find the libraries | |
| 27 it is linked to. This works only on ELF-based systems. | |
| 28 | |
| 29 --with-mangling=<map> | |
| 30 Mangle public symbols specified in <map> which is a comma-separated list of | |
| 31 name:mangled pairs. | |
| 32 | |
| 33 For example, to use ld's --wrap option as an alternative method for | |
| 34 overriding libc's malloc implementation, specify something like: | |
| 35 | |
| 36 --with-mangling=malloc:__wrap_malloc,free:__wrap_free[...] | |
| 37 | |
| 38 Note that mangling happens prior to application of the prefix specified by | |
| 39 --with-jemalloc-prefix, and mangled symbols are then ignored when applying | |
| 40 the prefix. | |
| 41 | |
| 42 --with-jemalloc-prefix=<prefix> | |
| 43 Prefix all public APIs with <prefix>. For example, if <prefix> is | |
| 44 "prefix_", API changes like the following occur: | |
| 45 | |
| 46 malloc() --> prefix_malloc() | |
| 47 malloc_conf --> prefix_malloc_conf | |
| 48 /etc/malloc.conf --> /etc/prefix_malloc.conf | |
| 49 MALLOC_CONF --> PREFIX_MALLOC_CONF | |
| 50 | |
| 51 This makes it possible to use jemalloc at the same time as the system | |
| 52 allocator, or even to use multiple copies of jemalloc simultaneously. | |
| 53 | |
| 54 By default, the prefix is "", except on OS X, where it is "je_". On OS X, | |
| 55 jemalloc overlays the default malloc zone, but makes no attempt to actually | |
| 56 replace the "malloc", "calloc", etc. symbols. | |
| 57 | |
| 58 --without-export | |
| 59 Don't export public APIs. This can be useful when building jemalloc as a | |
| 60 static library, or to avoid exporting public APIs when using the zone | |
| 61 allocator on OSX. | |
| 62 | |
| 63 --with-private-namespace=<prefix> | |
| 64 Prefix all library-private APIs with <prefix>. For shared libraries, | |
| 65 symbol visibility mechanisms prevent these symbols from being exported, but | |
| 66 for static libraries, naming collisions are a real possibility. By | |
| 67 default, the prefix is "" (empty string). | |
| 68 | |
| 69 --with-install-suffix=<suffix> | |
| 70 Append <suffix> to the base name of all installed files, such that multiple | |
| 71 versions of jemalloc can coexist in the same installation directory. For | |
| 72 example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0. | |
| 73 | |
| 74 --enable-cc-silence | |
| 75 Enable code that silences non-useful compiler warnings. This is helpful | |
| 76 when trying to tell serious warnings from those due to compiler | |
| 77 limitations, but it potentially incurs a performance penalty. | |
| 78 | |
| 79 --enable-debug | |
| 80 Enable assertions and validation code. This incurs a substantial | |
| 81 performance hit, but is very useful during application development. | |
| 82 | |
| 83 --disable-stats | |
| 84 Disable statistics gathering functionality. See the "opt.stats_print" | |
| 85 option documentation for usage details. | |
| 86 | |
| 87 --enable-prof | |
| 88 Enable heap profiling and leak detection functionality. See the "opt.prof" | |
| 89 option documentation for usage details. When enabled, there are several | |
| 90 approaches to backtracing, and the configure script chooses the first one | |
| 91 in the following list that appears to function correctly: | |
| 92 | |
| 93 + libunwind (requires --enable-prof-libunwind) | |
| 94 + libgcc (unless --disable-prof-libgcc) | |
| 95 + gcc intrinsics (unless --disable-prof-gcc) | |
| 96 | |
| 97 --enable-prof-libunwind | |
| 98 Use the libunwind library (http://www.nongnu.org/libunwind/) for stack | |
| 99 backtracing. | |
| 100 | |
| 101 --disable-prof-libgcc | |
| 102 Disable the use of libgcc's backtracing functionality. | |
| 103 | |
| 104 --disable-prof-gcc | |
| 105 Disable the use of gcc intrinsics for backtracing. | |
| 106 | |
| 107 --with-static-libunwind=<libunwind.a> | |
| 108 Statically link against the specified libunwind.a rather than dynamically | |
| 109 linking with -lunwind. | |
| 110 | |
| 111 --disable-tcache | |
| 112 Disable thread-specific caches for small objects. Objects are cached and | |
| 113 released in bulk, thus reducing the total number of mutex operations. See | |
| 114 the "opt.tcache" option for usage details. | |
| 115 | |
| 116 --enable-mremap | |
| 117 Enable huge realloc() via mremap(2). mremap() is disabled by default | |
| 118 because the flavor used is specific to Linux, which has a quirk in its | |
| 119 virtual memory allocation algorithm that causes semi-permanent VM map holes | |
| 120 under normal jemalloc operation. | |
| 121 | |
| 122 --disable-munmap | |
| 123 Disable virtual memory deallocation via munmap(2); instead keep track of | |
| 124 the virtual memory for later use. munmap() is disabled by default (i.e. | |
| 125 --disable-munmap is implied) on Linux, which has a quirk in its virtual | |
| 126 memory allocation algorithm that causes semi-permanent VM map holes under | |
| 127 normal jemalloc operation. | |
| 128 | |
| 129 --enable-dss | |
| 130 Enable support for page allocation/deallocation via sbrk(2), in addition to | |
| 131 mmap(2). | |
| 132 | |
| 133 --disable-fill | |
| 134 Disable support for junk/zero filling of memory, quarantine, and redzones. | |
| 135 See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option | |
| 136 documentation for usage details. | |
| 137 | |
| 138 --disable-valgrind | |
| 139 Disable support for Valgrind. | |
| 140 | |
| 141 --disable-experimental | |
| 142 Disable support for the experimental API (*allocm()). | |
| 143 | |
| 144 --enable-utrace | |
| 145 Enable utrace(2)-based allocation tracing. This feature is not broadly | |
| 146 portable (FreeBSD has it, but Linux and OS X do not). | |
| 147 | |
| 148 --enable-xmalloc | |
| 149 Enable support for optional immediate termination due to out-of-memory | |
| 150 errors, as is commonly implemented by "xmalloc" wrapper function for malloc. | |
| 151 See the "opt.xmalloc" option documentation for usage details. | |
| 152 | |
| 153 --enable-lazy-lock | |
| 154 Enable code that wraps pthread_create() to detect when an application | |
| 155 switches from single-threaded to multi-threaded mode, so that it can avoid | |
| 156 mutex locking/unlocking operations while in single-threaded mode. In | |
| 157 practice, this feature usually has little impact on performance unless | |
| 158 thread-specific caching is disabled. | |
| 159 | |
| 160 --disable-tls | |
| 161 Disable thread-local storage (TLS), which allows for fast access to | |
| 162 thread-local variables via the __thread keyword. If TLS is available, | |
| 163 jemalloc uses it for several purposes. | |
| 164 | |
| 165 --with-xslroot=<path> | |
| 166 Specify where to find DocBook XSL stylesheets when building the | |
| 167 documentation. | |
| 168 | |
| 169 The following environment variables (not a definitive list) impact configure's | |
| 170 behavior: | |
| 171 | |
| 172 CFLAGS="?" | |
| 173 Pass these flags to the compiler. You probably shouldn't define this unless | |
| 174 you know what you are doing. (Use EXTRA_CFLAGS instead.) | |
| 175 | |
| 176 EXTRA_CFLAGS="?" | |
| 177 Append these flags to CFLAGS. This makes it possible to add flags such as | |
| 178 -Werror, while allowing the configure script to determine what other flags | |
| 179 are appropriate for the specified configuration. | |
| 180 | |
| 181 The configure script specifically checks whether an optimization flag (-O*) | |
| 182 is specified in EXTRA_CFLAGS, and refrains from specifying an optimization | |
| 183 level if it finds that one has already been specified. | |
| 184 | |
| 185 CPPFLAGS="?" | |
| 186 Pass these flags to the C preprocessor. Note that CFLAGS is not passed to | |
| 187 'cpp' when 'configure' is looking for include files, so you must use | |
| 188 CPPFLAGS instead if you need to help 'configure' find header files. | |
| 189 | |
| 190 LD_LIBRARY_PATH="?" | |
| 191 'ld' uses this colon-separated list to find libraries. | |
| 192 | |
| 193 LDFLAGS="?" | |
| 194 Pass these flags when linking. | |
| 195 | |
| 196 PATH="?" | |
| 197 'configure' uses this to find programs. | |
| 198 | |
| 199 === Advanced compilation ======================================================= | |
| 200 | |
| 201 To build only parts of jemalloc, use the following targets: | |
| 202 | |
| 203 build_lib_shared | |
| 204 build_lib_static | |
| 205 build_lib | |
| 206 build_doc_html | |
| 207 build_doc_man | |
| 208 build_doc | |
| 209 | |
| 210 To install only parts of jemalloc, use the following targets: | |
| 211 | |
| 212 install_bin | |
| 213 install_include | |
| 214 install_lib_shared | |
| 215 install_lib_static | |
| 216 install_lib | |
| 217 install_doc_html | |
| 218 install_doc_man | |
| 219 install_doc | |
| 220 | |
| 221 To clean up build results to varying degrees, use the following make targets: | |
| 222 | |
| 223 clean | |
| 224 distclean | |
| 225 relclean | |
| 226 | |
| 227 === Advanced installation ====================================================== | |
| 228 | |
| 229 Optionally, define make variables when invoking make, including (not | |
| 230 exclusively): | |
| 231 | |
| 232 INCLUDEDIR="?" | |
| 233 Use this as the installation prefix for header files. | |
| 234 | |
| 235 LIBDIR="?" | |
| 236 Use this as the installation prefix for libraries. | |
| 237 | |
| 238 MANDIR="?" | |
| 239 Use this as the installation prefix for man pages. | |
| 240 | |
| 241 DESTDIR="?" | |
| 242 Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful | |
| 243 when installing to a different path than was specified via --prefix. | |
| 244 | |
| 245 CC="?" | |
| 246 Use this to invoke the C compiler. | |
| 247 | |
| 248 CFLAGS="?" | |
| 249 Pass these flags to the compiler. | |
| 250 | |
| 251 CPPFLAGS="?" | |
| 252 Pass these flags to the C preprocessor. | |
| 253 | |
| 254 LDFLAGS="?" | |
| 255 Pass these flags when linking. | |
| 256 | |
| 257 PATH="?" | |
| 258 Use this to search for programs used during configuration and building. | |
| 259 | |
| 260 === Development ================================================================ | |
| 261 | |
| 262 If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' | |
| 263 script rather than 'configure'. This re-generates 'configure', enables | |
| 264 configuration dependency rules, and enables re-generation of automatically | |
| 265 generated source files. | |
| 266 | |
| 267 The build system supports using an object directory separate from the source | |
| 268 tree. For example, you can create an 'obj' directory, and from within that | |
| 269 directory, issue configuration and build commands: | |
| 270 | |
| 271 autoconf | |
| 272 mkdir obj | |
| 273 cd obj | |
| 274 ../configure --enable-autogen | |
| 275 make | |
| 276 | |
| 277 === Documentation ============================================================== | |
| 278 | |
| 279 The manual page is generated in both html and roff formats. Any web browser | |
| 280 can be used to view the html manual. The roff manual page can be formatted | |
| 281 prior to installation via the following command: | |
| 282 | |
| 283 nroff -man -t doc/jemalloc.3 |
