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