Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 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> |
Jason Evans | 6c8b13b | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 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. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 28 | |
Jason Evans | 0a5489e | 2012-03-01 17:19:20 -0800 | [diff] [blame] | 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 | |
Jason Evans | 90895cf | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 42 | --with-jemalloc-prefix=<prefix> |
Jason Evans | e733970 | 2010-10-23 18:37:06 -0700 | [diff] [blame] | 43 | Prefix all public APIs with <prefix>. For example, if <prefix> is |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 44 | "prefix_", API changes like the following occur: |
Jason Evans | e733970 | 2010-10-23 18:37:06 -0700 | [diff] [blame] | 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 | |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 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. |
Jason Evans | 90895cf | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 53 | |
Jason Evans | 2dbecf1 | 2010-09-05 10:35:13 -0700 | [diff] [blame] | 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 | |
Mike Hommey | 9906660 | 2012-11-19 10:55:26 +0100 | [diff] [blame] | 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 | |
Jason Evans | 746e77a | 2011-07-30 16:40:52 -0700 | [diff] [blame] | 63 | --with-private-namespace=<prefix> |
Jason Evans | 86abd0d | 2013-11-30 15:25:42 -0800 | [diff] [blame] | 64 | Prefix all library-private APIs with <prefix>je_. For shared libraries, |
Jason Evans | 746e77a | 2011-07-30 16:40:52 -0700 | [diff] [blame] | 65 | symbol visibility mechanisms prevent these symbols from being exported, but |
| 66 | for static libraries, naming collisions are a real possibility. By |
Jason Evans | 86abd0d | 2013-11-30 15:25:42 -0800 | [diff] [blame] | 67 | default, <prefix> is empty, which results in a symbol prefix of je_ . |
Jason Evans | 746e77a | 2011-07-30 16:40:52 -0700 | [diff] [blame] | 68 | |
Jason Evans | b0fd501 | 2010-01-17 01:49:20 -0800 | [diff] [blame] | 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 | |
Jason Evans | 355b438 | 2010-09-20 19:20:48 -0700 | [diff] [blame] | 74 | --enable-cc-silence |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 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. |
Jason Evans | 355b438 | 2010-09-20 19:20:48 -0700 | [diff] [blame] | 78 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 79 | --enable-debug |
| 80 | Enable assertions and validation code. This incurs a substantial |
| 81 | performance hit, but is very useful during application development. |
Mike Hommey | 5135e34 | 2012-12-06 22:16:26 +0100 | [diff] [blame] | 82 | Implies --enable-ivsalloc. |
| 83 | |
Jason Evans | 748dfac | 2013-12-06 18:27:33 -0800 | [diff] [blame] | 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 | |
Mike Hommey | 5135e34 | 2012-12-06 22:16:26 +0100 | [diff] [blame] | 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. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 101 | |
Jason Evans | d073a32 | 2012-02-28 20:41:16 -0800 | [diff] [blame] | 102 | --disable-stats |
| 103 | Disable statistics gathering functionality. See the "opt.stats_print" |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 104 | option documentation for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 105 | |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 106 | --enable-prof |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 107 | Enable heap profiling and leak detection functionality. See the "opt.prof" |
Jason Evans | 77f350b | 2011-03-15 22:23:12 -0700 | [diff] [blame] | 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: |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 111 | |
Jason Evans | 77f350b | 2011-03-15 22:23:12 -0700 | [diff] [blame] | 112 | + libunwind (requires --enable-prof-libunwind) |
| 113 | + libgcc (unless --disable-prof-libgcc) |
| 114 | + gcc intrinsics (unless --disable-prof-gcc) |
Jason Evans | b27805b | 2010-02-10 18:15:53 -0800 | [diff] [blame] | 115 | |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 116 | --enable-prof-libunwind |
| 117 | Use the libunwind library (http://www.nongnu.org/libunwind/) for stack |
Jason Evans | 77f350b | 2011-03-15 22:23:12 -0700 | [diff] [blame] | 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. |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 125 | |
Jason Evans | ca6bd4f | 2010-03-02 14:12:58 -0800 | [diff] [blame] | 126 | --with-static-libunwind=<libunwind.a> |
| 127 | Statically link against the specified libunwind.a rather than dynamically |
| 128 | linking with -lunwind. |
| 129 | |
Jason Evans | 84cbbcb | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 130 | --disable-tcache |
Jason Evans | dafde14 | 2010-03-17 16:27:39 -0700 | [diff] [blame] | 131 | Disable thread-specific caches for small objects. Objects are cached and |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 132 | released in bulk, thus reducing the total number of mutex operations. See |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 133 | the "opt.tcache" option for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 134 | |
Jason Evans | 2e671ff | 2012-05-09 16:12:00 -0700 | [diff] [blame] | 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 | |
Jason Evans | 59ae276 | 2012-04-16 17:52:27 -0700 | [diff] [blame] | 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 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 148 | --enable-dss |
| 149 | Enable support for page allocation/deallocation via sbrk(2), in addition to |
| 150 | mmap(2). |
| 151 | |
Jason Evans | 777c191 | 2012-02-28 20:49:22 -0800 | [diff] [blame] | 152 | --disable-fill |
Jason Evans | 122449b | 2012-04-06 00:35:09 -0700 | [diff] [blame] | 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. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 159 | |
Jason Evans | 7e77eaf | 2012-03-02 17:47:37 -0800 | [diff] [blame] | 160 | --disable-experimental |
| 161 | Disable support for the experimental API (*allocm()). |
| 162 | |
Mike Hommey | d0357f7 | 2012-11-26 18:52:41 +0100 | [diff] [blame] | 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 | |
Jason Evans | b147611 | 2012-04-05 13:36:17 -0700 | [diff] [blame] | 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 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 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. |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 174 | See the "opt.xmalloc" option documentation for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 175 | |
Jason Evans | 0fee70d | 2012-02-13 12:36:11 -0800 | [diff] [blame] | 176 | --enable-lazy-lock |
| 177 | Enable code that wraps pthread_create() to detect when an application |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 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 |
Jason Evans | 84cbbcb | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 181 | thread-specific caching is disabled. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 182 | |
Jason Evans | 78d815c | 2010-01-17 14:06:20 -0800 | [diff] [blame] | 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, |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 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. |
Jason Evans | 78d815c | 2010-01-17 14:06:20 -0800 | [diff] [blame] | 191 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 192 | The following environment variables (not a definitive list) impact configure's |
| 193 | behavior: |
| 194 | |
| 195 | CFLAGS="?" |
| 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 | |
| 199 | EXTRA_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 | |
| 208 | CPPFLAGS="?" |
| 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 | |
| 213 | LD_LIBRARY_PATH="?" |
| 214 | 'ld' uses this colon-separated list to find libraries. |
| 215 | |
| 216 | LDFLAGS="?" |
| 217 | Pass these flags when linking. |
| 218 | |
| 219 | PATH="?" |
| 220 | 'configure' uses this to find programs. |
| 221 | |
| 222 | === Advanced compilation ======================================================= |
| 223 | |
Jason Evans | 7b398ac | 2012-03-02 16:38:37 -0800 | [diff] [blame] | 224 | To 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 | |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 233 | To install only parts of jemalloc, use the following targets: |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 234 | |
Jason Evans | 5523399 | 2010-04-11 19:02:43 -0700 | [diff] [blame] | 235 | install_bin |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 236 | install_include |
Jason Evans | 7b398ac | 2012-03-02 16:38:37 -0800 | [diff] [blame] | 237 | install_lib_shared |
| 238 | install_lib_static |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 239 | install_lib |
Jason Evans | 7b398ac | 2012-03-02 16:38:37 -0800 | [diff] [blame] | 240 | install_doc_html |
| 241 | install_doc_man |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 242 | install_doc |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 243 | |
| 244 | To clean up build results to varying degrees, use the following make targets: |
| 245 | |
| 246 | clean |
| 247 | distclean |
| 248 | relclean |
| 249 | |
| 250 | === Advanced installation ====================================================== |
| 251 | |
| 252 | Optionally, define make variables when invoking make, including (not |
| 253 | exclusively): |
| 254 | |
| 255 | INCLUDEDIR="?" |
| 256 | Use this as the installation prefix for header files. |
| 257 | |
| 258 | LIBDIR="?" |
| 259 | Use this as the installation prefix for libraries. |
| 260 | |
| 261 | MANDIR="?" |
| 262 | Use this as the installation prefix for man pages. |
| 263 | |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 264 | DESTDIR="?" |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 265 | Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful |
| 266 | when installing to a different path than was specified via --prefix. |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 267 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 268 | CC="?" |
| 269 | Use this to invoke the C compiler. |
| 270 | |
| 271 | CFLAGS="?" |
| 272 | Pass these flags to the compiler. |
| 273 | |
| 274 | CPPFLAGS="?" |
| 275 | Pass these flags to the C preprocessor. |
| 276 | |
| 277 | LDFLAGS="?" |
| 278 | Pass these flags when linking. |
| 279 | |
| 280 | PATH="?" |
| 281 | Use this to search for programs used during configuration and building. |
| 282 | |
| 283 | === Development ================================================================ |
| 284 | |
| 285 | If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' |
| 286 | script rather than 'configure'. This re-generates 'configure', enables |
| 287 | configuration dependency rules, and enables re-generation of automatically |
| 288 | generated source files. |
| 289 | |
| 290 | The build system supports using an object directory separate from the source |
| 291 | tree. For example, you can create an 'obj' directory, and from within that |
| 292 | directory, issue configuration and build commands: |
| 293 | |
| 294 | autoconf |
| 295 | mkdir obj |
| 296 | cd obj |
| 297 | ../configure --enable-autogen |
| 298 | make |
Jason Evans | 7e11b38 | 2010-09-11 22:47:39 -0700 | [diff] [blame] | 299 | |
| 300 | === Documentation ============================================================== |
| 301 | |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 302 | The manual page is generated in both html and roff formats. Any web browser |
| 303 | can be used to view the html manual. The roff manual page can be formatted |
Jason Evans | 079687b | 2012-04-23 12:49:23 -0700 | [diff] [blame] | 304 | prior to installation via the following command: |
Jason Evans | 7e11b38 | 2010-09-11 22:47:39 -0700 | [diff] [blame] | 305 | |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 306 | nroff -man -t doc/jemalloc.3 |