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 | 90895cf | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 29 | --with-jemalloc-prefix=<prefix> |
Jason Evans | e733970 | 2010-10-23 18:37:06 -0700 | [diff] [blame] | 30 | Prefix all public APIs with <prefix>. For example, if <prefix> is |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 31 | "prefix_", API changes like the following occur: |
Jason Evans | e733970 | 2010-10-23 18:37:06 -0700 | [diff] [blame] | 32 | |
| 33 | malloc() --> prefix_malloc() |
| 34 | malloc_conf --> prefix_malloc_conf |
| 35 | /etc/malloc.conf --> /etc/prefix_malloc.conf |
| 36 | MALLOC_CONF --> PREFIX_MALLOC_CONF |
| 37 | |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 38 | This makes it possible to use jemalloc at the same time as the system |
| 39 | allocator, or even to use multiple copies of jemalloc simultaneously. |
Jason Evans | 90895cf | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 40 | |
Jason Evans | 2dbecf1 | 2010-09-05 10:35:13 -0700 | [diff] [blame] | 41 | By default, the prefix is "", except on OS X, where it is "je_". On OS X, |
| 42 | jemalloc overlays the default malloc zone, but makes no attempt to actually |
| 43 | replace the "malloc", "calloc", etc. symbols. |
| 44 | |
Jason Evans | 746e77a | 2011-07-30 16:40:52 -0700 | [diff] [blame^] | 45 | --with-private-namespace=<prefix> |
| 46 | Prefix all library-private APIs with <prefix>. For shared libraries, |
| 47 | symbol visibility mechanisms prevent these symbols from being exported, but |
| 48 | for static libraries, naming collisions are a real possibility. By |
| 49 | default, the prefix is "" (empty string). |
| 50 | |
Jason Evans | b0fd501 | 2010-01-17 01:49:20 -0800 | [diff] [blame] | 51 | --with-install-suffix=<suffix> |
| 52 | Append <suffix> to the base name of all installed files, such that multiple |
| 53 | versions of jemalloc can coexist in the same installation directory. For |
| 54 | example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0. |
| 55 | |
Jason Evans | 355b438 | 2010-09-20 19:20:48 -0700 | [diff] [blame] | 56 | --enable-cc-silence |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 57 | Enable code that silences non-useful compiler warnings. This is helpful |
| 58 | when trying to tell serious warnings from those due to compiler |
| 59 | limitations, but it potentially incurs a performance penalty. |
Jason Evans | 355b438 | 2010-09-20 19:20:48 -0700 | [diff] [blame] | 60 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 61 | --enable-debug |
| 62 | Enable assertions and validation code. This incurs a substantial |
| 63 | performance hit, but is very useful during application development. |
| 64 | |
| 65 | --enable-stats |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 66 | Enable statistics gathering functionality. See the "opt.stats_print" |
| 67 | option documentation for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 68 | |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 69 | --enable-prof |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 70 | Enable heap profiling and leak detection functionality. See the "opt.prof" |
Jason Evans | 77f350b | 2011-03-15 22:23:12 -0700 | [diff] [blame] | 71 | option documentation for usage details. When enabled, there are several |
| 72 | approaches to backtracing, and the configure script chooses the first one |
| 73 | in the following list that appears to function correctly: |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 74 | |
Jason Evans | 77f350b | 2011-03-15 22:23:12 -0700 | [diff] [blame] | 75 | + libunwind (requires --enable-prof-libunwind) |
| 76 | + libgcc (unless --disable-prof-libgcc) |
| 77 | + gcc intrinsics (unless --disable-prof-gcc) |
Jason Evans | b27805b | 2010-02-10 18:15:53 -0800 | [diff] [blame] | 78 | |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 79 | --enable-prof-libunwind |
| 80 | Use the libunwind library (http://www.nongnu.org/libunwind/) for stack |
Jason Evans | 77f350b | 2011-03-15 22:23:12 -0700 | [diff] [blame] | 81 | backtracing. |
| 82 | |
| 83 | --disable-prof-libgcc |
| 84 | Disable the use of libgcc's backtracing functionality. |
| 85 | |
| 86 | --disable-prof-gcc |
| 87 | Disable the use of gcc intrinsics for backtracing. |
Jason Evans | 6109fe0 | 2010-02-10 10:37:56 -0800 | [diff] [blame] | 88 | |
Jason Evans | ca6bd4f | 2010-03-02 14:12:58 -0800 | [diff] [blame] | 89 | --with-static-libunwind=<libunwind.a> |
| 90 | Statically link against the specified libunwind.a rather than dynamically |
| 91 | linking with -lunwind. |
| 92 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 93 | --disable-tiny |
| 94 | Disable tiny (sub-quantum-sized) object support. Technically it is not |
| 95 | legal for a malloc implementation to allocate objects with less than |
| 96 | quantum alignment (8 or 16 bytes, depending on architecture), but in |
Jason Evans | a9b0125 | 2009-06-26 16:34:13 -0700 | [diff] [blame] | 97 | practice it never causes any problems if, for example, 4-byte allocations |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 98 | are 4-byte-aligned. |
| 99 | |
Jason Evans | 84cbbcb | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 100 | --disable-tcache |
Jason Evans | dafde14 | 2010-03-17 16:27:39 -0700 | [diff] [blame] | 101 | Disable thread-specific caches for small objects. Objects are cached and |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 102 | released in bulk, thus reducing the total number of mutex operations. See |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 103 | the "opt.tcache" option for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 104 | |
Jason Evans | 4201af0 | 2010-01-24 02:53:40 -0800 | [diff] [blame] | 105 | --enable-swap |
| 106 | Enable mmap()ed swap file support. When this feature is built in, it is |
| 107 | possible to specify one or more files that act as backing store. This |
| 108 | effectively allows for per application swap files. |
| 109 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 110 | --enable-dss |
| 111 | Enable support for page allocation/deallocation via sbrk(2), in addition to |
| 112 | mmap(2). |
| 113 | |
| 114 | --enable-fill |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 115 | Enable support for junk/zero filling of memory. See the "opt.junk"/ |
| 116 | "opt.zero" option documentation for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 117 | |
| 118 | --enable-xmalloc |
| 119 | Enable support for optional immediate termination due to out-of-memory |
| 120 | errors, as is commonly implemented by "xmalloc" wrapper function for malloc. |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 121 | See the "opt.xmalloc" option documentation for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 122 | |
| 123 | --enable-sysv |
| 124 | Enable support for System V semantics, wherein malloc(0) returns NULL |
Jason Evans | 379f847 | 2010-10-24 16:18:29 -0700 | [diff] [blame] | 125 | rather than a minimal allocation. See the "opt.sysv" option documentation |
| 126 | for usage details. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 127 | |
| 128 | --enable-dynamic-page-shift |
| 129 | Under most conditions, the system page size never changes (usually 4KiB or |
| 130 | 8KiB, depending on architecture and configuration), and unless this option |
| 131 | is enabled, jemalloc assumes that page size can safely be determined during |
| 132 | configuration and hard-coded. Enabling dynamic page size determination has |
| 133 | a measurable impact on performance, since the compiler is forced to load |
| 134 | the page size from memory rather than embedding immediate values. |
| 135 | |
| 136 | --disable-lazy-lock |
| 137 | Disable code that wraps pthread_create() to detect when an application |
| 138 | switches from single-threaded to multi-threaded mode, so that it can avoid |
| 139 | mutex locking/unlocking operations while in single-threaded mode. In |
| 140 | practice, this feature usually has little impact on performance unless |
Jason Evans | 84cbbcb | 2009-12-29 00:09:15 -0800 | [diff] [blame] | 141 | thread-specific caching is disabled. |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 142 | |
Jason Evans | 78d815c | 2010-01-17 14:06:20 -0800 | [diff] [blame] | 143 | --disable-tls |
| 144 | Disable thread-local storage (TLS), which allows for fast access to |
| 145 | thread-local variables via the __thread keyword. If TLS is available, |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 146 | jemalloc uses it for several purposes. |
| 147 | |
| 148 | --with-xslroot=<path> |
| 149 | Specify where to find DocBook XSL stylesheets when building the |
| 150 | documentation. |
Jason Evans | 78d815c | 2010-01-17 14:06:20 -0800 | [diff] [blame] | 151 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 152 | The following environment variables (not a definitive list) impact configure's |
| 153 | behavior: |
| 154 | |
| 155 | CFLAGS="?" |
| 156 | Pass these flags to the compiler. You probably shouldn't define this unless |
| 157 | you know what you are doing. (Use EXTRA_CFLAGS instead.) |
| 158 | |
| 159 | EXTRA_CFLAGS="?" |
| 160 | Append these flags to CFLAGS. This makes it possible to add flags such as |
| 161 | -Werror, while allowing the configure script to determine what other flags |
| 162 | are appropriate for the specified configuration. |
| 163 | |
| 164 | The configure script specifically checks whether an optimization flag (-O*) |
| 165 | is specified in EXTRA_CFLAGS, and refrains from specifying an optimization |
| 166 | level if it finds that one has already been specified. |
| 167 | |
| 168 | CPPFLAGS="?" |
| 169 | Pass these flags to the C preprocessor. Note that CFLAGS is not passed to |
| 170 | 'cpp' when 'configure' is looking for include files, so you must use |
| 171 | CPPFLAGS instead if you need to help 'configure' find header files. |
| 172 | |
| 173 | LD_LIBRARY_PATH="?" |
| 174 | 'ld' uses this colon-separated list to find libraries. |
| 175 | |
| 176 | LDFLAGS="?" |
| 177 | Pass these flags when linking. |
| 178 | |
| 179 | PATH="?" |
| 180 | 'configure' uses this to find programs. |
| 181 | |
| 182 | === Advanced compilation ======================================================= |
| 183 | |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 184 | To install only parts of jemalloc, use the following targets: |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 185 | |
Jason Evans | 5523399 | 2010-04-11 19:02:43 -0700 | [diff] [blame] | 186 | install_bin |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 187 | install_include |
| 188 | install_lib |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 189 | install_doc |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 190 | |
| 191 | To clean up build results to varying degrees, use the following make targets: |
| 192 | |
| 193 | clean |
| 194 | distclean |
| 195 | relclean |
| 196 | |
| 197 | === Advanced installation ====================================================== |
| 198 | |
| 199 | Optionally, define make variables when invoking make, including (not |
| 200 | exclusively): |
| 201 | |
| 202 | INCLUDEDIR="?" |
| 203 | Use this as the installation prefix for header files. |
| 204 | |
| 205 | LIBDIR="?" |
| 206 | Use this as the installation prefix for libraries. |
| 207 | |
| 208 | MANDIR="?" |
| 209 | Use this as the installation prefix for man pages. |
| 210 | |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 211 | DESTDIR="?" |
Jason Evans | 2b76979 | 2010-12-16 14:13:46 -0800 | [diff] [blame] | 212 | Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful |
| 213 | when installing to a different path than was specified via --prefix. |
Jason Evans | cfeccd3 | 2010-03-03 15:48:20 -0800 | [diff] [blame] | 214 | |
Jason Evans | cc00a15 | 2009-06-25 18:06:48 -0700 | [diff] [blame] | 215 | CC="?" |
| 216 | Use this to invoke the C compiler. |
| 217 | |
| 218 | CFLAGS="?" |
| 219 | Pass these flags to the compiler. |
| 220 | |
| 221 | CPPFLAGS="?" |
| 222 | Pass these flags to the C preprocessor. |
| 223 | |
| 224 | LDFLAGS="?" |
| 225 | Pass these flags when linking. |
| 226 | |
| 227 | PATH="?" |
| 228 | Use this to search for programs used during configuration and building. |
| 229 | |
| 230 | === Development ================================================================ |
| 231 | |
| 232 | If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' |
| 233 | script rather than 'configure'. This re-generates 'configure', enables |
| 234 | configuration dependency rules, and enables re-generation of automatically |
| 235 | generated source files. |
| 236 | |
| 237 | The build system supports using an object directory separate from the source |
| 238 | tree. For example, you can create an 'obj' directory, and from within that |
| 239 | directory, issue configuration and build commands: |
| 240 | |
| 241 | autoconf |
| 242 | mkdir obj |
| 243 | cd obj |
| 244 | ../configure --enable-autogen |
| 245 | make |
Jason Evans | 7e11b38 | 2010-09-11 22:47:39 -0700 | [diff] [blame] | 246 | |
| 247 | === Documentation ============================================================== |
| 248 | |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 249 | The manual page is generated in both html and roff formats. Any web browser |
| 250 | can be used to view the html manual. The roff manual page can be formatted |
Jason Evans | 3af8334 | 2010-10-24 16:48:52 -0700 | [diff] [blame] | 251 | prior to installation via any of the following commands: |
Jason Evans | 7e11b38 | 2010-09-11 22:47:39 -0700 | [diff] [blame] | 252 | |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 253 | nroff -man -t doc/jemalloc.3 |
Jason Evans | 3af8334 | 2010-10-24 16:48:52 -0700 | [diff] [blame] | 254 | |
Jason Evans | aee7fd2 | 2010-11-24 22:00:02 -0800 | [diff] [blame] | 255 | groff -man -t -Tps doc/jemalloc.3 | ps2pdf - doc/jemalloc.3.pdf |
Jason Evans | 3af8334 | 2010-10-24 16:48:52 -0700 | [diff] [blame] | 256 | |
| 257 | (cd doc; groff -man -man-ext -t -Thtml jemalloc.3 > jemalloc.3.html) |