1Building and installing jemalloc can be as simple as typing the following while 2in the root directory of the source tree: 3 4 ./configure 5 make 6 make install 7 8=== Advanced configuration ===================================================== 9 10The 'configure' script supports numerous options that allow control of which 11functionality is enabled, where jemalloc is installed, etc. Optionally, pass 12any 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--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 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--enable-mremap 136 Enable huge realloc() via mremap(2). mremap() is disabled by default 137 because the flavor used is specific to Linux, which has a quirk in its 138 virtual memory allocation algorithm that causes semi-permanent VM map holes 139 under normal jemalloc operation. 140 141--disable-munmap 142 Disable virtual memory deallocation via munmap(2); instead keep track of 143 the virtual memory for later use. munmap() is disabled by default (i.e. 144 --disable-munmap is implied) on Linux, which has a quirk in its virtual 145 memory allocation algorithm that causes semi-permanent VM map holes under 146 normal jemalloc operation. 147 148--enable-dss 149 Enable support for page allocation/deallocation via sbrk(2), in addition to 150 mmap(2). 151 152--disable-fill 153 Disable support for junk/zero filling of memory, quarantine, and redzones. 154 See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option 155 documentation for usage details. 156 157--disable-valgrind 158 Disable support for Valgrind. 159 160--disable-experimental 161 Disable support for the experimental API (*allocm()). 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--with-xslroot=<path> 189 Specify where to find DocBook XSL stylesheets when building the 190 documentation. 191 192The following environment variables (not a definitive list) impact configure's 193behavior: 194 195CFLAGS="?" 196 Pass these flags to the compiler. You probably shouldn't define this unless 197 you know what you are doing. (Use EXTRA_CFLAGS instead.) 198 199EXTRA_CFLAGS="?" 200 Append these flags to CFLAGS. This makes it possible to add flags such as 201 -Werror, while allowing the configure script to determine what other flags 202 are appropriate for the specified configuration. 203 204 The configure script specifically checks whether an optimization flag (-O*) 205 is specified in EXTRA_CFLAGS, and refrains from specifying an optimization 206 level if it finds that one has already been specified. 207 208CPPFLAGS="?" 209 Pass these flags to the C preprocessor. Note that CFLAGS is not passed to 210 'cpp' when 'configure' is looking for include files, so you must use 211 CPPFLAGS instead if you need to help 'configure' find header files. 212 213LD_LIBRARY_PATH="?" 214 'ld' uses this colon-separated list to find libraries. 215 216LDFLAGS="?" 217 Pass these flags when linking. 218 219PATH="?" 220 'configure' uses this to find programs. 221 222=== Advanced compilation ======================================================= 223 224To build only parts of jemalloc, use the following targets: 225 226 build_lib_shared 227 build_lib_static 228 build_lib 229 build_doc_html 230 build_doc_man 231 build_doc 232 233To install only parts of jemalloc, use the following targets: 234 235 install_bin 236 install_include 237 install_lib_shared 238 install_lib_static 239 install_lib 240 install_doc_html 241 install_doc_man 242 install_doc 243 244To clean up build results to varying degrees, use the following make targets: 245 246 clean 247 distclean 248 relclean 249 250=== Advanced installation ====================================================== 251 252Optionally, define make variables when invoking make, including (not 253exclusively): 254 255INCLUDEDIR="?" 256 Use this as the installation prefix for header files. 257 258LIBDIR="?" 259 Use this as the installation prefix for libraries. 260 261MANDIR="?" 262 Use this as the installation prefix for man pages. 263 264DESTDIR="?" 265 Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful 266 when installing to a different path than was specified via --prefix. 267 268CC="?" 269 Use this to invoke the C compiler. 270 271CFLAGS="?" 272 Pass these flags to the compiler. 273 274CPPFLAGS="?" 275 Pass these flags to the C preprocessor. 276 277LDFLAGS="?" 278 Pass these flags when linking. 279 280PATH="?" 281 Use this to search for programs used during configuration and building. 282 283=== Development ================================================================ 284 285If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' 286script rather than 'configure'. This re-generates 'configure', enables 287configuration dependency rules, and enables re-generation of automatically 288generated source files. 289 290The build system supports using an object directory separate from the source 291tree. For example, you can create an 'obj' directory, and from within that 292directory, issue configuration and build commands: 293 294 autoconf 295 mkdir obj 296 cd obj 297 ../configure --enable-autogen 298 make 299 300=== Documentation ============================================================== 301 302The manual page is generated in both html and roff formats. Any web browser 303can be used to view the html manual. The roff manual page can be formatted 304prior to installation via the following command: 305 306 nroff -man -t doc/jemalloc.3 307