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