1 Building and installing a packaged release of jemalloc can be as simple as 2 typing the following while in the root directory of the source tree: 3 4 ./configure 5 make 6 make install 7 8 If building from unpackaged developer sources, the simplest command sequence 9 that might work is: 10 11 ./autogen.sh 12 make dist 13 make 14 make install 15 16 Note that documentation is not built by the default target because doing so 17 would create a dependency on xsltproc in packaged releases, hence the 18 requirement to either run 'make dist' or avoid installing docs via the various 19 install_* targets documented below. 20 21 === Advanced configuration ===================================================== 22 23 The 'configure' script supports numerous options that allow control of which 24 functionality is enabled, where jemalloc is installed, etc. Optionally, pass 25 any of the following arguments (not a definitive list) to 'configure': 26 27 --help 28 Print a definitive list of options. 29 30 --prefix=<install-root-dir> 31 Set the base directory in which to install. For example: 32 33 ./configure --prefix=/usr/local 34 35 will cause files to be installed into /usr/local/include, /usr/local/lib, 36 and /usr/local/man. 37 38 --with-rpath=<colon-separated-rpath> 39 Embed one or more library paths, so that libjemalloc can find the libraries 40 it is linked to. This works only on ELF-based systems. 41 42 --with-mangling=<map> 43 Mangle public symbols specified in <map> which is a comma-separated list of 44 name:mangled pairs. 45 46 For example, to use ld's --wrap option as an alternative method for 47 overriding libc's malloc implementation, specify something like: 48 49 --with-mangling=malloc:__wrap_malloc,free:__wrap_free[...] 50 51 Note that mangling happens prior to application of the prefix specified by 52 --with-jemalloc-prefix, and mangled symbols are then ignored when applying 53 the prefix. 54 55 --with-jemalloc-prefix=<prefix> 56 Prefix all public APIs with <prefix>. For example, if <prefix> is 57 "prefix_", API changes like the following occur: 58 59 malloc() --> prefix_malloc() 60 malloc_conf --> prefix_malloc_conf 61 /etc/malloc.conf --> /etc/prefix_malloc.conf 62 MALLOC_CONF --> PREFIX_MALLOC_CONF 63 64 This makes it possible to use jemalloc at the same time as the system 65 allocator, or even to use multiple copies of jemalloc simultaneously. 66 67 By default, the prefix is "", except on OS X, where it is "je_". On OS X, 68 jemalloc overlays the default malloc zone, but makes no attempt to actually 69 replace the "malloc", "calloc", etc. symbols. 70 71 --without-export 72 Don't export public APIs. This can be useful when building jemalloc as a 73 static library, or to avoid exporting public APIs when using the zone 74 allocator on OSX. 75 76 --with-private-namespace=<prefix> 77 Prefix all library-private APIs with <prefix>je_. For shared libraries, 78 symbol visibility mechanisms prevent these symbols from being exported, but 79 for static libraries, naming collisions are a real possibility. By 80 default, <prefix> is empty, which results in a symbol prefix of je_ . 81 82 --with-install-suffix=<suffix> 83 Append <suffix> to the base name of all installed files, such that multiple 84 versions of jemalloc can coexist in the same installation directory. For 85 example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0. 86 87 --disable-cc-silence 88 Disable code that silences non-useful compiler warnings. This is mainly 89 useful during development when auditing the set of warnings that are being 90 silenced. 91 92 --enable-debug 93 Enable assertions and validation code. This incurs a substantial 94 performance hit, but is very useful during application development. 95 Implies --enable-ivsalloc. 96 97 --enable-code-coverage 98 Enable code coverage support, for use during jemalloc test development. 99 Additional testing targets are available if this option is enabled: 100 101 coverage 102 coverage_unit 103 coverage_integration 104 coverage_stress 105 106 These targets do not clear code coverage results from previous runs, and 107 there are interactions between the various coverage targets, so it is 108 usually advisable to run 'make clean' between repeated code coverage runs. 109 110 --disable-stats 111 Disable statistics gathering functionality. See the "opt.stats_print" 112 option documentation for usage details. 113 114 --enable-ivsalloc 115 Enable validation code, which verifies that pointers reside within 116 jemalloc-owned chunks before dereferencing them. This incurs a minor 117 performance hit. 118 119 --enable-prof 120 Enable heap profiling and leak detection functionality. See the "opt.prof" 121 option documentation for usage details. When enabled, there are several 122 approaches to backtracing, and the configure script chooses the first one 123 in the following list that appears to function correctly: 124 125 + libunwind (requires --enable-prof-libunwind) 126 + libgcc (unless --disable-prof-libgcc) 127 + gcc intrinsics (unless --disable-prof-gcc) 128 129 --enable-prof-libunwind 130 Use the libunwind library (http://www.nongnu.org/libunwind/) for stack 131 backtracing. 132 133 --disable-prof-libgcc 134 Disable the use of libgcc's backtracing functionality. 135 136 --disable-prof-gcc 137 Disable the use of gcc intrinsics for backtracing. 138 139 --with-static-libunwind=<libunwind.a> 140 Statically link against the specified libunwind.a rather than dynamically 141 linking with -lunwind. 142 143 --disable-tcache 144 Disable thread-specific caches for small objects. Objects are cached and 145 released in bulk, thus reducing the total number of mutex operations. See 146 the "opt.tcache" option for usage details. 147 148 --disable-munmap 149 Disable virtual memory deallocation via munmap(2); instead keep track of 150 the virtual memory for later use. munmap() is disabled by default (i.e. 151 --disable-munmap is implied) on Linux, which has a quirk in its virtual 152 memory allocation algorithm that causes semi-permanent VM map holes under 153 normal jemalloc operation. 154 155 --disable-fill 156 Disable support for junk/zero filling of memory, quarantine, and redzones. 157 See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option 158 documentation for usage details. 159 160 --disable-valgrind 161 Disable support for Valgrind. 162 163 --disable-zone-allocator 164 Disable zone allocator for Darwin. This means jemalloc won't be hooked as 165 the default allocator on OSX/iOS. 166 167 --enable-utrace 168 Enable utrace(2)-based allocation tracing. This feature is not broadly 169 portable (FreeBSD has it, but Linux and OS X do not). 170 171 --enable-xmalloc 172 Enable support for optional immediate termination due to out-of-memory 173 errors, as is commonly implemented by "xmalloc" wrapper function for malloc. 174 See the "opt.xmalloc" option documentation for usage details. 175 176 --enable-lazy-lock 177 Enable code that wraps pthread_create() to detect when an application 178 switches from single-threaded to multi-threaded mode, so that it can avoid 179 mutex locking/unlocking operations while in single-threaded mode. In 180 practice, this feature usually has little impact on performance unless 181 thread-specific caching is disabled. 182 183 --disable-tls 184 Disable thread-local storage (TLS), which allows for fast access to 185 thread-local variables via the __thread keyword. If TLS is available, 186 jemalloc uses it for several purposes. 187 188 --disable-cache-oblivious 189 Disable cache-oblivious large allocation alignment for large allocation 190 requests with no alignment constraints. If this feature is disabled, all 191 large allocations are page-aligned as an implementation artifact, which can 192 severely harm CPU cache utilization. However, the cache-oblivious layout 193 comes at the cost of one extra page per large allocation, which in the 194 most extreme case increases physical memory usage for the 16 KiB size class 195 to 20 KiB. 196 197 --with-xslroot=<path> 198 Specify where to find DocBook XSL stylesheets when building the 199 documentation. 200 201 --with-lg-page=<lg-page> 202 Specify the base 2 log of the system page size. This option is only useful 203 when cross compiling, since the configure script automatically determines 204 the host's page size by default. 205 206 --with-lg-page-sizes=<lg-page-sizes> 207 Specify the comma-separated base 2 logs of the page sizes to support. This 208 option may be useful when cross-compiling in combination with 209 --with-lg-page, but its primary use case is for integration with FreeBSD's 210 libc, wherein jemalloc is embedded. 211 212 --with-lg-size-class-group=<lg-size-class-group> 213 Specify the base 2 log of how many size classes to use for each doubling in 214 size. By default jemalloc uses <lg-size-class-group>=2, which results in 215 e.g. the following size classes: 216 217 [...], 64, 218 80, 96, 112, 128, 219 160, [...] 220 221 <lg-size-class-group>=3 results in e.g. the following size classes: 222 223 [...], 64, 224 72, 80, 88, 96, 104, 112, 120, 128, 225 144, [...] 226 227 The minimal <lg-size-class-group>=0 causes jemalloc to only provide size 228 classes that are powers of 2: 229 230 [...], 231 64, 232 128, 233 256, 234 [...] 235 236 An implementation detail currently limits the total number of small size 237 classes to 255, and a compilation error will result if the 238 <lg-size-class-group> you specify cannot be supported. The limit is 239 roughly <lg-size-class-group>=4, depending on page size. 240 241 --with-lg-quantum=<lg-quantum> 242 Specify the base 2 log of the minimum allocation alignment. jemalloc needs 243 to know the minimum alignment that meets the following C standard 244 requirement (quoted from the April 12, 2011 draft of the C11 standard): 245 246 The pointer returned if the allocation succeeds is suitably aligned so 247 that it may be assigned to a pointer to any type of object with a 248 fundamental alignment requirement and then used to access such an object 249 or an array of such objects in the space allocated [...] 250 251 This setting is architecture-specific, and although jemalloc includes known 252 safe values for the most commonly used modern architectures, there is a 253 wrinkle related to GNU libc (glibc) that may impact your choice of 254 <lg-quantum>. On most modern architectures, this mandates 16-byte alignment 255 (<lg-quantum>=4), but the glibc developers chose not to meet this 256 requirement for performance reasons. An old discussion can be found at 257 https://sourceware.org/bugzilla/show_bug.cgi?id=206 . Unlike glibc, 258 jemalloc does follow the C standard by default (caveat: jemalloc 259 technically cheats if --with-lg-tiny-min is smaller than 260 --with-lg-quantum), but the fact that Linux systems already work around 261 this allocator noncompliance means that it is generally safe in practice to 262 let jemalloc's minimum alignment follow glibc's lead. If you specify 263 --with-lg-quantum=3 during configuration, jemalloc will provide additional 264 size classes that are not 16-byte-aligned (24, 40, and 56, assuming 265 --with-lg-size-class-group=2). 266 267 --with-lg-tiny-min=<lg-tiny-min> 268 Specify the base 2 log of the minimum tiny size class to support. Tiny 269 size classes are powers of 2 less than the quantum, and are only 270 incorporated if <lg-tiny-min> is less than <lg-quantum> (see 271 --with-lg-quantum). Tiny size classes technically violate the C standard 272 requirement for minimum alignment, and crashes could conceivably result if 273 the compiler were to generate instructions that made alignment assumptions, 274 both because illegal instruction traps could result, and because accesses 275 could straddle page boundaries and cause segmentation faults due to 276 accessing unmapped addresses. 277 278 The default of <lg-tiny-min>=3 works well in practice even on architectures 279 that technically require 16-byte alignment, probably for the same reason 280 --with-lg-quantum=3 works. Smaller tiny size classes can, and will, cause 281 crashes (see https://bugzilla.mozilla.org/show_bug.cgi?id=691003 for an 282 example). 283 284 This option is rarely useful, and is mainly provided as documentation of a 285 subtle implementation detail. If you do use this option, specify a 286 value in [3, ..., <lg-quantum>]. 287 288 The following environment variables (not a definitive list) impact configure's 289 behavior: 290 291 CFLAGS="?" 292 Pass these flags to the compiler. You probably shouldn't define this unless 293 you know what you are doing. (Use EXTRA_CFLAGS instead.) 294 295 EXTRA_CFLAGS="?" 296 Append these flags to CFLAGS. This makes it possible to add flags such as 297 -Werror, while allowing the configure script to determine what other flags 298 are appropriate for the specified configuration. 299 300 The configure script specifically checks whether an optimization flag (-O*) 301 is specified in EXTRA_CFLAGS, and refrains from specifying an optimization 302 level if it finds that one has already been specified. 303 304 CPPFLAGS="?" 305 Pass these flags to the C preprocessor. Note that CFLAGS is not passed to 306 'cpp' when 'configure' is looking for include files, so you must use 307 CPPFLAGS instead if you need to help 'configure' find header files. 308 309 LD_LIBRARY_PATH="?" 310 'ld' uses this colon-separated list to find libraries. 311 312 LDFLAGS="?" 313 Pass these flags when linking. 314 315 PATH="?" 316 'configure' uses this to find programs. 317 318 === Advanced compilation ======================================================= 319 320 To build only parts of jemalloc, use the following targets: 321 322 build_lib_shared 323 build_lib_static 324 build_lib 325 build_doc_html 326 build_doc_man 327 build_doc 328 329 To install only parts of jemalloc, use the following targets: 330 331 install_bin 332 install_include 333 install_lib_shared 334 install_lib_static 335 install_lib 336 install_doc_html 337 install_doc_man 338 install_doc 339 340 To clean up build results to varying degrees, use the following make targets: 341 342 clean 343 distclean 344 relclean 345 346 === Advanced installation ====================================================== 347 348 Optionally, define make variables when invoking make, including (not 349 exclusively): 350 351 INCLUDEDIR="?" 352 Use this as the installation prefix for header files. 353 354 LIBDIR="?" 355 Use this as the installation prefix for libraries. 356 357 MANDIR="?" 358 Use this as the installation prefix for man pages. 359 360 DESTDIR="?" 361 Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful 362 when installing to a different path than was specified via --prefix. 363 364 CC="?" 365 Use this to invoke the C compiler. 366 367 CFLAGS="?" 368 Pass these flags to the compiler. 369 370 CPPFLAGS="?" 371 Pass these flags to the C preprocessor. 372 373 LDFLAGS="?" 374 Pass these flags when linking. 375 376 PATH="?" 377 Use this to search for programs used during configuration and building. 378 379 === Development ================================================================ 380 381 If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' 382 script rather than 'configure'. This re-generates 'configure', enables 383 configuration dependency rules, and enables re-generation of automatically 384 generated source files. 385 386 The build system supports using an object directory separate from the source 387 tree. For example, you can create an 'obj' directory, and from within that 388 directory, issue configuration and build commands: 389 390 autoconf 391 mkdir obj 392 cd obj 393 ../configure --enable-autogen 394 make 395 396 === Documentation ============================================================== 397 398 The manual page is generated in both html and roff formats. Any web browser 399 can be used to view the html manual. The roff manual page can be formatted 400 prior to installation via the following command: 401 402 nroff -man -t doc/jemalloc.3 403
