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> |
| 64 | Prefix all library-private APIs with <prefix>. 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, the prefix is "" (empty string). |
| 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 | |
| 84 | --enable-ivsalloc |
| 85 | Enable validation code, which verifies that pointers reside within |
| 86 | jemalloc-owned chunks before dereferencing them. This incurs a substantial |
| 87 | performance hit. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 88 | |
Jason Evans | d073a32 | 2012-02-28 20:41:16 -0800 | [diff] [blame] | 89 | --disable-stats |
| 90 | Disable statistics gathering functionality. See the "opt.stats_print" |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 91 | option documentation for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 92 | |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 93 | --enable-prof |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 94 | Enable heap profiling and leak detection functionality. See the "opt.prof" |
Jason Evans | 77f350b | 2011-03-15 22:23:12 -0700 | [diff] [blame] | 95 | option documentation for usage details. When enabled, there are several |
| 96 | approaches to backtracing, and the configure script chooses the first one |
| 97 | in the following list that appears to function correctly: |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 98 | |
Jason Evans | 77f350b | 2011-03-15 22:23:12 -0700 | [diff] [blame] | 99 | + libunwind (requires --enable-prof-libunwind) |
| 100 | + libgcc (unless --disable-prof-libgcc) |
| 101 | + gcc intrinsics (unless --disable-prof-gcc) |
Jason Evans | b27805b | 2010-02-10 18:15:53 -0800 | [diff] [blame] | 102 | |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 103 | --enable-prof-libunwind |
| 104 | Use the libunwind library (http://www.nongnu.org/libunwind/) for stack |
Jason Evans | 77f350b | 2011-03-15 22:23:12 -0700 | [diff] [blame] | 105 | backtracing. |
| 106 | |
| 107 | --disable-prof-libgcc |
| 108 | Disable the use of libgcc's backtracing functionality. |
| 109 | |
| 110 | --disable-prof-gcc |
| 111 | Disable the use of gcc intrinsics for backtracing. |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 112 | |
Jason Evans | ca6bd4f | 2010-03-02 14:12:58 -0800 | [diff] [blame] | 113 | --with-static-libunwind=<libunwind.a> |
| 114 | Statically link against the specified libunwind.a rather than dynamically |
| 115 | linking with -lunwind. |
| 116 | |
Jason Evans | 84cbbcb | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 117 | --disable-tcache |
Jason Evans | dafde14 | 2010-03-17 16:27:39 -0700 | [diff] [blame] | 118 | Disable thread-specific caches for small objects. Objects are cached and |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 119 | released in bulk, thus reducing the total number of mutex operations. See |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 120 | the "opt.tcache" option for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 121 | |
Jason Evans | 2e671ff | 2012-05-09 16:12:00 -0700 | [diff] [blame] | 122 | --enable-mremap |
| 123 | Enable huge realloc() via mremap(2). mremap() is disabled by default |
| 124 | because the flavor used is specific to Linux, which has a quirk in its |
| 125 | virtual memory allocation algorithm that causes semi-permanent VM map holes |
| 126 | under normal jemalloc operation. |
| 127 | |
Jason Evans | 59ae276 | 2012-04-16 17:52:27 -0700 | [diff] [blame] | 128 | --disable-munmap |
| 129 | Disable virtual memory deallocation via munmap(2); instead keep track of |
| 130 | the virtual memory for later use. munmap() is disabled by default (i.e. |
| 131 | --disable-munmap is implied) on Linux, which has a quirk in its virtual |
| 132 | memory allocation algorithm that causes semi-permanent VM map holes under |
| 133 | normal jemalloc operation. |
| 134 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 135 | --enable-dss |
| 136 | Enable support for page allocation/deallocation via sbrk(2), in addition to |
| 137 | mmap(2). |
| 138 | |
Jason Evans | 777c191 | 2012-02-28 20:49:22 -0800 | [diff] [blame] | 139 | --disable-fill |
Jason Evans | 122449b | 2012-04-06 00:35:09 -0700 | [diff] [blame] | 140 | Disable support for junk/zero filling of memory, quarantine, and redzones. |
| 141 | See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option |
| 142 | documentation for usage details. |
| 143 | |
| 144 | --disable-valgrind |
| 145 | Disable support for Valgrind. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 146 | |
Jason Evans | 7e77eaf | 2012-03-02 17:47:37 -0800 | [diff] [blame] | 147 | --disable-experimental |
| 148 | Disable support for the experimental API (*allocm()). |
| 149 | |
Mike Hommey | d0357f7 | 2012-11-26 18:52:41 +0100 | [diff] [blame] | 150 | --disable-zone-allocator |
| 151 | Disable zone allocator for Darwin. This means jemalloc won't be hooked as |
| 152 | the default allocator on OSX/iOS. |
| 153 | |
Jason Evans | b147611 | 2012-04-05 13:36:17 -0700 | [diff] [blame] | 154 | --enable-utrace |
| 155 | Enable utrace(2)-based allocation tracing. This feature is not broadly |
| 156 | portable (FreeBSD has it, but Linux and OS X do not). |
| 157 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 158 | --enable-xmalloc |
| 159 | Enable support for optional immediate termination due to out-of-memory |
| 160 | errors, as is commonly implemented by "xmalloc" wrapper function for malloc. |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 161 | See the "opt.xmalloc" option documentation for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 162 | |
Jason Evans | 0fee70d | 2012-02-13 12:36:11 -0800 | [diff] [blame] | 163 | --enable-lazy-lock |
| 164 | Enable code that wraps pthread_create() to detect when an application |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 165 | switches from single-threaded to multi-threaded mode, so that it can avoid |
| 166 | mutex locking/unlocking operations while in single-threaded mode. In |
| 167 | practice, this feature usually has little impact on performance unless |
Jason Evans | 84cbbcb | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 168 | thread-specific caching is disabled. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 169 | |
Jason Evans | 78d815c | 2010-01-17 14:06:20 -0800 | [diff] [blame] | 170 | --disable-tls |
| 171 | Disable thread-local storage (TLS), which allows for fast access to |
| 172 | thread-local variables via the __thread keyword. If TLS is available, |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 173 | jemalloc uses it for several purposes. |
| 174 | |
| 175 | --with-xslroot=<path> |
| 176 | Specify where to find DocBook XSL stylesheets when building the |
| 177 | documentation. |
Jason Evans | 78d815c | 2010-01-17 14:06:20 -0800 | [diff] [blame] | 178 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 179 | The following environment variables (not a definitive list) impact configure's |
| 180 | behavior: |
| 181 | |
| 182 | CFLAGS="?" |
| 183 | Pass these flags to the compiler. You probably shouldn't define this unless |
| 184 | you know what you are doing. (Use EXTRA_CFLAGS instead.) |
| 185 | |
| 186 | EXTRA_CFLAGS="?" |
| 187 | Append these flags to CFLAGS. This makes it possible to add flags such as |
| 188 | -Werror, while allowing the configure script to determine what other flags |
| 189 | are appropriate for the specified configuration. |
| 190 | |
| 191 | The configure script specifically checks whether an optimization flag (-O*) |
| 192 | is specified in EXTRA_CFLAGS, and refrains from specifying an optimization |
| 193 | level if it finds that one has already been specified. |
| 194 | |
| 195 | CPPFLAGS="?" |
| 196 | Pass these flags to the C preprocessor. Note that CFLAGS is not passed to |
| 197 | 'cpp' when 'configure' is looking for include files, so you must use |
| 198 | CPPFLAGS instead if you need to help 'configure' find header files. |
| 199 | |
| 200 | LD_LIBRARY_PATH="?" |
| 201 | 'ld' uses this colon-separated list to find libraries. |
| 202 | |
| 203 | LDFLAGS="?" |
| 204 | Pass these flags when linking. |
| 205 | |
| 206 | PATH="?" |
| 207 | 'configure' uses this to find programs. |
| 208 | |
| 209 | === Advanced compilation ======================================================= |
| 210 | |
Jason Evans | 7b398ac | 2012-03-02 16:38:37 -0800 | [diff] [blame] | 211 | To build only parts of jemalloc, use the following targets: |
| 212 | |
| 213 | build_lib_shared |
| 214 | build_lib_static |
| 215 | build_lib |
| 216 | build_doc_html |
| 217 | build_doc_man |
| 218 | build_doc |
| 219 | |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 220 | To install only parts of jemalloc, use the following targets: |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 221 | |
Jason Evans | 5523399 | 2010-04-11 19:02:43 -0700 | [diff] [blame] | 222 | install_bin |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 223 | install_include |
Jason Evans | 7b398ac | 2012-03-02 16:38:37 -0800 | [diff] [blame] | 224 | install_lib_shared |
| 225 | install_lib_static |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 226 | install_lib |
Jason Evans | 7b398ac | 2012-03-02 16:38:37 -0800 | [diff] [blame] | 227 | install_doc_html |
| 228 | install_doc_man |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 229 | install_doc |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 230 | |
| 231 | To clean up build results to varying degrees, use the following make targets: |
| 232 | |
| 233 | clean |
| 234 | distclean |
| 235 | relclean |
| 236 | |
| 237 | === Advanced installation ====================================================== |
| 238 | |
| 239 | Optionally, define make variables when invoking make, including (not |
| 240 | exclusively): |
| 241 | |
| 242 | INCLUDEDIR="?" |
| 243 | Use this as the installation prefix for header files. |
| 244 | |
| 245 | LIBDIR="?" |
| 246 | Use this as the installation prefix for libraries. |
| 247 | |
| 248 | MANDIR="?" |
| 249 | Use this as the installation prefix for man pages. |
| 250 | |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 251 | DESTDIR="?" |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 252 | Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful |
| 253 | when installing to a different path than was specified via --prefix. |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 254 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 255 | CC="?" |
| 256 | Use this to invoke the C compiler. |
| 257 | |
| 258 | CFLAGS="?" |
| 259 | Pass these flags to the compiler. |
| 260 | |
| 261 | CPPFLAGS="?" |
| 262 | Pass these flags to the C preprocessor. |
| 263 | |
| 264 | LDFLAGS="?" |
| 265 | Pass these flags when linking. |
| 266 | |
| 267 | PATH="?" |
| 268 | Use this to search for programs used during configuration and building. |
| 269 | |
| 270 | === Development ================================================================ |
| 271 | |
| 272 | If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' |
| 273 | script rather than 'configure'. This re-generates 'configure', enables |
| 274 | configuration dependency rules, and enables re-generation of automatically |
| 275 | generated source files. |
| 276 | |
| 277 | The build system supports using an object directory separate from the source |
| 278 | tree. For example, you can create an 'obj' directory, and from within that |
| 279 | directory, issue configuration and build commands: |
| 280 | |
| 281 | autoconf |
| 282 | mkdir obj |
| 283 | cd obj |
| 284 | ../configure --enable-autogen |
| 285 | make |
Jason Evans | 7e11b38 | 2010-09-11 22:47:39 -0700 | [diff] [blame] | 286 | |
| 287 | === Documentation ============================================================== |
| 288 | |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 289 | The manual page is generated in both html and roff formats. Any web browser |
| 290 | 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] | 291 | prior to installation via the following command: |
Jason Evans | 7e11b38 | 2010-09-11 22:47:39 -0700 | [diff] [blame] | 292 | |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 293 | nroff -man -t doc/jemalloc.3 |