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