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>je_. 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, <prefix> is empty, which results in a symbol prefix of je_ . 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 --disable-cc-silence 75 Disable code that silences non-useful compiler warnings. This is mainly 76 useful during development when auditing the set of warnings that are being 77 silenced. 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 Implies --enable-ivsalloc. 83 84 --enable-code-coverage 85 Enable code coverage support, for use during jemalloc test development. 86 Additional testing targets are available if this option is enabled: 87 88 coverage 89 coverage_unit 90 coverage_integration 91 coverage_stress 92 93 These targets do not clear code coverage results from previous runs, and 94 there are interactions between the various coverage targets, so it is 95 usually advisable to run 'make clean' between repeated code coverage runs. 96 97 --enable-ivsalloc 98 Enable validation code, which verifies that pointers reside within 99 jemalloc-owned chunks before dereferencing them. This incurs a substantial 100 performance hit. 101 102 --disable-stats 103 Disable statistics gathering functionality. See the "opt.stats_print" 104 option documentation for usage details. 105 106 --enable-prof 107 Enable heap profiling and leak detection functionality. See the "opt.prof" 108 option documentation for usage details. When enabled, there are several 109 approaches to backtracing, and the configure script chooses the first one 110 in the following list that appears to function correctly: 111 112 + libunwind (requires --enable-prof-libunwind) 113 + libgcc (unless --disable-prof-libgcc) 114 + gcc intrinsics (unless --disable-prof-gcc) 115 116 --enable-prof-libunwind 117 Use the libunwind library (http://www.nongnu.org/libunwind/) for stack 118 backtracing. 119 120 --disable-prof-libgcc 121 Disable the use of libgcc's backtracing functionality. 122 123 --disable-prof-gcc 124 Disable the use of gcc intrinsics for backtracing. 125 126 --with-static-libunwind=<libunwind.a> 127 Statically link against the specified libunwind.a rather than dynamically 128 linking with -lunwind. 129 130 --disable-tcache 131 Disable thread-specific caches for small objects. Objects are cached and 132 released in bulk, thus reducing the total number of mutex operations. See 133 the "opt.tcache" option for usage details. 134 135 --disable-munmap 136 Disable virtual memory deallocation via munmap(2); instead keep track of 137 the virtual memory for later use. munmap() is disabled by default (i.e. 138 --disable-munmap is implied) on Linux, which has a quirk in its virtual 139 memory allocation algorithm that causes semi-permanent VM map holes under 140 normal jemalloc operation. 141 142 --disable-fill 143 Disable support for junk/zero filling of memory, quarantine, and redzones. 144 See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option 145 documentation for usage details. 146 147 --disable-valgrind 148 Disable support for Valgrind. 149 150 --disable-zone-allocator 151 Disable zone allocator for Darwin. This means jemalloc won't be hooked as 152 the default allocator on OSX/iOS. 153 154 --enable-utrace 155 Enable utrace(2)-based allocation tracing. This feature is not broadly 156 portable (FreeBSD has it, but Linux and OS X do not). 157 158 --enable-xmalloc 159 Enable support for optional immediate termination due to out-of-memory 160 errors, as is commonly implemented by "xmalloc" wrapper function for malloc. 161 See the "opt.xmalloc" option documentation for usage details. 162 163 --enable-lazy-lock 164 Enable code that wraps pthread_create() to detect when an application 165 switches from single-threaded to multi-threaded mode, so that it can avoid 166 mutex locking/unlocking operations while in single-threaded mode. In 167 practice, this feature usually has little impact on performance unless 168 thread-specific caching is disabled. 169 170 --disable-tls 171 Disable thread-local storage (TLS), which allows for fast access to 172 thread-local variables via the __thread keyword. If TLS is available, 173 jemalloc uses it for several purposes. 174 175 --with-xslroot=<path> 176 Specify where to find DocBook XSL stylesheets when building the 177 documentation. 178 179 The following environment variables (not a definitive list) impact configure's 180 behavior: 181 182 CFLAGS="?" 183 Pass these flags to the compiler. You probably shouldn't define this unless 184 you know what you are doing. (Use EXTRA_CFLAGS instead.) 185 186 EXTRA_CFLAGS="?" 187 Append these flags to CFLAGS. This makes it possible to add flags such as 188 -Werror, while allowing the configure script to determine what other flags 189 are appropriate for the specified configuration. 190 191 The configure script specifically checks whether an optimization flag (-O*) 192 is specified in EXTRA_CFLAGS, and refrains from specifying an optimization 193 level if it finds that one has already been specified. 194 195 CPPFLAGS="?" 196 Pass these flags to the C preprocessor. Note that CFLAGS is not passed to 197 'cpp' when 'configure' is looking for include files, so you must use 198 CPPFLAGS instead if you need to help 'configure' find header files. 199 200 LD_LIBRARY_PATH="?" 201 'ld' uses this colon-separated list to find libraries. 202 203 LDFLAGS="?" 204 Pass these flags when linking. 205 206 PATH="?" 207 'configure' uses this to find programs. 208 209 === Advanced compilation ======================================================= 210 211 To build only parts of jemalloc, use the following targets: 212 213 build_lib_shared 214 build_lib_static 215 build_lib 216 build_doc_html 217 build_doc_man 218 build_doc 219 220 To install only parts of jemalloc, use the following targets: 221 222 install_bin 223 install_include 224 install_lib_shared 225 install_lib_static 226 install_lib 227 install_doc_html 228 install_doc_man 229 install_doc 230 231 To clean up build results to varying degrees, use the following make targets: 232 233 clean 234 distclean 235 relclean 236 237 === Advanced installation ====================================================== 238 239 Optionally, define make variables when invoking make, including (not 240 exclusively): 241 242 INCLUDEDIR="?" 243 Use this as the installation prefix for header files. 244 245 LIBDIR="?" 246 Use this as the installation prefix for libraries. 247 248 MANDIR="?" 249 Use this as the installation prefix for man pages. 250 251 DESTDIR="?" 252 Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful 253 when installing to a different path than was specified via --prefix. 254 255 CC="?" 256 Use this to invoke the C compiler. 257 258 CFLAGS="?" 259 Pass these flags to the compiler. 260 261 CPPFLAGS="?" 262 Pass these flags to the C preprocessor. 263 264 LDFLAGS="?" 265 Pass these flags when linking. 266 267 PATH="?" 268 Use this to search for programs used during configuration and building. 269 270 === Development ================================================================ 271 272 If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' 273 script rather than 'configure'. This re-generates 'configure', enables 274 configuration dependency rules, and enables re-generation of automatically 275 generated source files. 276 277 The build system supports using an object directory separate from the source 278 tree. For example, you can create an 'obj' directory, and from within that 279 directory, issue configuration and build commands: 280 281 autoconf 282 mkdir obj 283 cd obj 284 ../configure --enable-autogen 285 make 286 287 === Documentation ============================================================== 288 289 The manual page is generated in both html and roff formats. Any web browser 290 can be used to view the html manual. The roff manual page can be formatted 291 prior to installation via the following command: 292 293 nroff -man -t doc/jemalloc.3 294
