]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | Building and installing a packaged release of jemalloc can be as simple as |
2 | typing the following while in the root directory of the source tree: | |
970d7e83 LB |
3 | |
4 | ./configure | |
5 | make | |
6 | make install | |
7 | ||
1a4d82fc JJ |
8 | If building from unpackaged developer sources, the simplest command sequence |
9 | that might work is: | |
10 | ||
11 | ./autogen.sh | |
12 | make dist | |
13 | make | |
14 | make install | |
15 | ||
16 | Note that documentation is not built by the default target because doing so | |
17 | would create a dependency on xsltproc in packaged releases, hence the | |
18 | requirement to either run 'make dist' or avoid installing docs via the various | |
19 | install_* targets documented below. | |
20 | ||
970d7e83 LB |
21 | === Advanced configuration ===================================================== |
22 | ||
23 | The 'configure' script supports numerous options that allow control of which | |
24 | functionality is enabled, where jemalloc is installed, etc. Optionally, pass | |
25 | any of the following arguments (not a definitive list) to 'configure': | |
26 | ||
27 | --help | |
28 | Print a definitive list of options. | |
29 | ||
30 | --prefix=<install-root-dir> | |
31 | Set the base directory in which to install. For example: | |
32 | ||
33 | ./configure --prefix=/usr/local | |
34 | ||
35 | will cause files to be installed into /usr/local/include, /usr/local/lib, | |
36 | and /usr/local/man. | |
37 | ||
3b2f2976 XL |
38 | --with-version=<major>.<minor>.<bugfix>-<nrev>-g<gid> |
39 | Use the specified version string rather than trying to generate one (if in | |
40 | a git repository) or use existing the VERSION file (if present). | |
41 | ||
970d7e83 LB |
42 | --with-rpath=<colon-separated-rpath> |
43 | Embed one or more library paths, so that libjemalloc can find the libraries | |
44 | it is linked to. This works only on ELF-based systems. | |
45 | ||
46 | --with-mangling=<map> | |
47 | Mangle public symbols specified in <map> which is a comma-separated list of | |
48 | name:mangled pairs. | |
49 | ||
50 | For example, to use ld's --wrap option as an alternative method for | |
51 | overriding libc's malloc implementation, specify something like: | |
52 | ||
53 | --with-mangling=malloc:__wrap_malloc,free:__wrap_free[...] | |
54 | ||
55 | Note that mangling happens prior to application of the prefix specified by | |
56 | --with-jemalloc-prefix, and mangled symbols are then ignored when applying | |
57 | the prefix. | |
58 | ||
59 | --with-jemalloc-prefix=<prefix> | |
60 | Prefix all public APIs with <prefix>. For example, if <prefix> is | |
61 | "prefix_", API changes like the following occur: | |
62 | ||
63 | malloc() --> prefix_malloc() | |
64 | malloc_conf --> prefix_malloc_conf | |
65 | /etc/malloc.conf --> /etc/prefix_malloc.conf | |
66 | MALLOC_CONF --> PREFIX_MALLOC_CONF | |
67 | ||
68 | This makes it possible to use jemalloc at the same time as the system | |
69 | allocator, or even to use multiple copies of jemalloc simultaneously. | |
70 | ||
71 | By default, the prefix is "", except on OS X, where it is "je_". On OS X, | |
72 | jemalloc overlays the default malloc zone, but makes no attempt to actually | |
73 | replace the "malloc", "calloc", etc. symbols. | |
74 | ||
75 | --without-export | |
1a4d82fc | 76 | Don't export public APIs. This can be useful when building jemalloc as a |
970d7e83 LB |
77 | static library, or to avoid exporting public APIs when using the zone |
78 | allocator on OSX. | |
79 | ||
80 | --with-private-namespace=<prefix> | |
1a4d82fc | 81 | Prefix all library-private APIs with <prefix>je_. For shared libraries, |
970d7e83 LB |
82 | symbol visibility mechanisms prevent these symbols from being exported, but |
83 | for static libraries, naming collisions are a real possibility. By | |
1a4d82fc | 84 | default, <prefix> is empty, which results in a symbol prefix of je_ . |
970d7e83 LB |
85 | |
86 | --with-install-suffix=<suffix> | |
87 | Append <suffix> to the base name of all installed files, such that multiple | |
88 | versions of jemalloc can coexist in the same installation directory. For | |
89 | example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0. | |
90 | ||
54a0048b SL |
91 | --with-malloc-conf=<malloc_conf> |
92 | Embed <malloc_conf> as a run-time options string that is processed prior to | |
93 | the malloc_conf global variable, the /etc/malloc.conf symlink, and the | |
94 | MALLOC_CONF environment variable. For example, to change the default chunk | |
95 | size to 256 KiB: | |
96 | ||
97 | --with-malloc-conf=lg_chunk:18 | |
98 | ||
1a4d82fc JJ |
99 | --disable-cc-silence |
100 | Disable code that silences non-useful compiler warnings. This is mainly | |
101 | useful during development when auditing the set of warnings that are being | |
102 | silenced. | |
970d7e83 LB |
103 | |
104 | --enable-debug | |
105 | Enable assertions and validation code. This incurs a substantial | |
106 | performance hit, but is very useful during application development. | |
107 | Implies --enable-ivsalloc. | |
108 | ||
1a4d82fc JJ |
109 | --enable-code-coverage |
110 | Enable code coverage support, for use during jemalloc test development. | |
111 | Additional testing targets are available if this option is enabled: | |
112 | ||
113 | coverage | |
114 | coverage_unit | |
115 | coverage_integration | |
116 | coverage_stress | |
117 | ||
118 | These targets do not clear code coverage results from previous runs, and | |
119 | there are interactions between the various coverage targets, so it is | |
120 | usually advisable to run 'make clean' between repeated code coverage runs. | |
121 | ||
7453a54e SL |
122 | --disable-stats |
123 | Disable statistics gathering functionality. See the "opt.stats_print" | |
124 | option documentation for usage details. | |
125 | ||
54a0048b SL |
126 | --enable-ivsalloc |
127 | Enable validation code, which verifies that pointers reside within | |
128 | jemalloc-owned chunks before dereferencing them. This incurs a minor | |
129 | performance hit. | |
130 | ||
970d7e83 LB |
131 | --enable-prof |
132 | Enable heap profiling and leak detection functionality. See the "opt.prof" | |
133 | option documentation for usage details. When enabled, there are several | |
134 | approaches to backtracing, and the configure script chooses the first one | |
135 | in the following list that appears to function correctly: | |
136 | ||
137 | + libunwind (requires --enable-prof-libunwind) | |
138 | + libgcc (unless --disable-prof-libgcc) | |
139 | + gcc intrinsics (unless --disable-prof-gcc) | |
140 | ||
141 | --enable-prof-libunwind | |
142 | Use the libunwind library (http://www.nongnu.org/libunwind/) for stack | |
143 | backtracing. | |
144 | ||
145 | --disable-prof-libgcc | |
146 | Disable the use of libgcc's backtracing functionality. | |
147 | ||
148 | --disable-prof-gcc | |
149 | Disable the use of gcc intrinsics for backtracing. | |
150 | ||
151 | --with-static-libunwind=<libunwind.a> | |
152 | Statically link against the specified libunwind.a rather than dynamically | |
153 | linking with -lunwind. | |
154 | ||
155 | --disable-tcache | |
156 | Disable thread-specific caches for small objects. Objects are cached and | |
157 | released in bulk, thus reducing the total number of mutex operations. See | |
158 | the "opt.tcache" option for usage details. | |
159 | ||
3b2f2976 XL |
160 | --disable-thp |
161 | Disable transparent huge page (THP) integration. On systems with THP | |
162 | support, THPs are explicitly disabled as a side effect of unused dirty page | |
163 | purging for chunks that back small and/or large allocations, because such | |
164 | chunks typically comprise active, unused dirty, and untouched clean | |
165 | pages. | |
166 | ||
970d7e83 LB |
167 | --disable-munmap |
168 | Disable virtual memory deallocation via munmap(2); instead keep track of | |
169 | the virtual memory for later use. munmap() is disabled by default (i.e. | |
170 | --disable-munmap is implied) on Linux, which has a quirk in its virtual | |
171 | memory allocation algorithm that causes semi-permanent VM map holes under | |
172 | normal jemalloc operation. | |
173 | ||
970d7e83 LB |
174 | --disable-fill |
175 | Disable support for junk/zero filling of memory, quarantine, and redzones. | |
176 | See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option | |
177 | documentation for usage details. | |
178 | ||
179 | --disable-valgrind | |
180 | Disable support for Valgrind. | |
181 | ||
970d7e83 | 182 | --disable-zone-allocator |
1a4d82fc | 183 | Disable zone allocator for Darwin. This means jemalloc won't be hooked as |
970d7e83 LB |
184 | the default allocator on OSX/iOS. |
185 | ||
186 | --enable-utrace | |
187 | Enable utrace(2)-based allocation tracing. This feature is not broadly | |
188 | portable (FreeBSD has it, but Linux and OS X do not). | |
189 | ||
190 | --enable-xmalloc | |
191 | Enable support for optional immediate termination due to out-of-memory | |
192 | errors, as is commonly implemented by "xmalloc" wrapper function for malloc. | |
193 | See the "opt.xmalloc" option documentation for usage details. | |
194 | ||
195 | --enable-lazy-lock | |
196 | Enable code that wraps pthread_create() to detect when an application | |
197 | switches from single-threaded to multi-threaded mode, so that it can avoid | |
198 | mutex locking/unlocking operations while in single-threaded mode. In | |
199 | practice, this feature usually has little impact on performance unless | |
200 | thread-specific caching is disabled. | |
201 | ||
202 | --disable-tls | |
203 | Disable thread-local storage (TLS), which allows for fast access to | |
204 | thread-local variables via the __thread keyword. If TLS is available, | |
205 | jemalloc uses it for several purposes. | |
206 | ||
54a0048b SL |
207 | --disable-cache-oblivious |
208 | Disable cache-oblivious large allocation alignment for large allocation | |
209 | requests with no alignment constraints. If this feature is disabled, all | |
210 | large allocations are page-aligned as an implementation artifact, which can | |
211 | severely harm CPU cache utilization. However, the cache-oblivious layout | |
212 | comes at the cost of one extra page per large allocation, which in the | |
213 | most extreme case increases physical memory usage for the 16 KiB size class | |
214 | to 20 KiB. | |
215 | ||
3b2f2976 XL |
216 | --disable-syscall |
217 | Disable use of syscall(2) rather than {open,read,write,close}(2). This is | |
218 | intended as a workaround for systems that place security limitations on | |
219 | syscall(2). | |
220 | ||
970d7e83 LB |
221 | --with-xslroot=<path> |
222 | Specify where to find DocBook XSL stylesheets when building the | |
223 | documentation. | |
224 | ||
54a0048b SL |
225 | --with-lg-page=<lg-page> |
226 | Specify the base 2 log of the system page size. This option is only useful | |
227 | when cross compiling, since the configure script automatically determines | |
228 | the host's page size by default. | |
229 | ||
230 | --with-lg-page-sizes=<lg-page-sizes> | |
231 | Specify the comma-separated base 2 logs of the page sizes to support. This | |
232 | option may be useful when cross-compiling in combination with | |
233 | --with-lg-page, but its primary use case is for integration with FreeBSD's | |
234 | libc, wherein jemalloc is embedded. | |
235 | ||
236 | --with-lg-size-class-group=<lg-size-class-group> | |
237 | Specify the base 2 log of how many size classes to use for each doubling in | |
238 | size. By default jemalloc uses <lg-size-class-group>=2, which results in | |
239 | e.g. the following size classes: | |
240 | ||
241 | [...], 64, | |
242 | 80, 96, 112, 128, | |
243 | 160, [...] | |
244 | ||
245 | <lg-size-class-group>=3 results in e.g. the following size classes: | |
246 | ||
247 | [...], 64, | |
248 | 72, 80, 88, 96, 104, 112, 120, 128, | |
249 | 144, [...] | |
250 | ||
251 | The minimal <lg-size-class-group>=0 causes jemalloc to only provide size | |
252 | classes that are powers of 2: | |
253 | ||
254 | [...], | |
255 | 64, | |
256 | 128, | |
257 | 256, | |
258 | [...] | |
259 | ||
260 | An implementation detail currently limits the total number of small size | |
261 | classes to 255, and a compilation error will result if the | |
262 | <lg-size-class-group> you specify cannot be supported. The limit is | |
263 | roughly <lg-size-class-group>=4, depending on page size. | |
264 | ||
265 | --with-lg-quantum=<lg-quantum> | |
266 | Specify the base 2 log of the minimum allocation alignment. jemalloc needs | |
267 | to know the minimum alignment that meets the following C standard | |
268 | requirement (quoted from the April 12, 2011 draft of the C11 standard): | |
269 | ||
270 | The pointer returned if the allocation succeeds is suitably aligned so | |
271 | that it may be assigned to a pointer to any type of object with a | |
272 | fundamental alignment requirement and then used to access such an object | |
273 | or an array of such objects in the space allocated [...] | |
274 | ||
275 | This setting is architecture-specific, and although jemalloc includes known | |
276 | safe values for the most commonly used modern architectures, there is a | |
277 | wrinkle related to GNU libc (glibc) that may impact your choice of | |
278 | <lg-quantum>. On most modern architectures, this mandates 16-byte alignment | |
279 | (<lg-quantum>=4), but the glibc developers chose not to meet this | |
280 | requirement for performance reasons. An old discussion can be found at | |
281 | https://sourceware.org/bugzilla/show_bug.cgi?id=206 . Unlike glibc, | |
282 | jemalloc does follow the C standard by default (caveat: jemalloc | |
283 | technically cheats if --with-lg-tiny-min is smaller than | |
284 | --with-lg-quantum), but the fact that Linux systems already work around | |
285 | this allocator noncompliance means that it is generally safe in practice to | |
286 | let jemalloc's minimum alignment follow glibc's lead. If you specify | |
287 | --with-lg-quantum=3 during configuration, jemalloc will provide additional | |
288 | size classes that are not 16-byte-aligned (24, 40, and 56, assuming | |
289 | --with-lg-size-class-group=2). | |
290 | ||
291 | --with-lg-tiny-min=<lg-tiny-min> | |
292 | Specify the base 2 log of the minimum tiny size class to support. Tiny | |
293 | size classes are powers of 2 less than the quantum, and are only | |
294 | incorporated if <lg-tiny-min> is less than <lg-quantum> (see | |
295 | --with-lg-quantum). Tiny size classes technically violate the C standard | |
296 | requirement for minimum alignment, and crashes could conceivably result if | |
297 | the compiler were to generate instructions that made alignment assumptions, | |
298 | both because illegal instruction traps could result, and because accesses | |
299 | could straddle page boundaries and cause segmentation faults due to | |
300 | accessing unmapped addresses. | |
301 | ||
302 | The default of <lg-tiny-min>=3 works well in practice even on architectures | |
303 | that technically require 16-byte alignment, probably for the same reason | |
304 | --with-lg-quantum=3 works. Smaller tiny size classes can, and will, cause | |
305 | crashes (see https://bugzilla.mozilla.org/show_bug.cgi?id=691003 for an | |
306 | example). | |
307 | ||
308 | This option is rarely useful, and is mainly provided as documentation of a | |
309 | subtle implementation detail. If you do use this option, specify a | |
310 | value in [3, ..., <lg-quantum>]. | |
311 | ||
970d7e83 LB |
312 | The following environment variables (not a definitive list) impact configure's |
313 | behavior: | |
314 | ||
315 | CFLAGS="?" | |
3b2f2976 XL |
316 | Pass these flags to the C compiler. Any flags set by the configure script |
317 | are prepended, which means explicitly set flags generally take precedence. | |
318 | Take care when specifying flags such as -Werror, because configure tests may | |
319 | be affected in undesirable ways. | |
970d7e83 LB |
320 | |
321 | EXTRA_CFLAGS="?" | |
3b2f2976 XL |
322 | Append these flags to CFLAGS, without passing them to the compiler during |
323 | configuration. This makes it possible to add flags such as -Werror, while | |
324 | allowing the configure script to determine what other flags are appropriate | |
325 | for the specified configuration. | |
970d7e83 LB |
326 | |
327 | CPPFLAGS="?" | |
328 | Pass these flags to the C preprocessor. Note that CFLAGS is not passed to | |
329 | 'cpp' when 'configure' is looking for include files, so you must use | |
330 | CPPFLAGS instead if you need to help 'configure' find header files. | |
331 | ||
332 | LD_LIBRARY_PATH="?" | |
333 | 'ld' uses this colon-separated list to find libraries. | |
334 | ||
335 | LDFLAGS="?" | |
336 | Pass these flags when linking. | |
337 | ||
338 | PATH="?" | |
339 | 'configure' uses this to find programs. | |
340 | ||
3b2f2976 XL |
341 | In some cases it may be necessary to work around configuration results that do |
342 | not match reality. For example, Linux 4.5 added support for the MADV_FREE flag | |
343 | to madvise(2), which can cause problems if building on a host with MADV_FREE | |
344 | support and deploying to a target without. To work around this, use a cache | |
345 | file to override the relevant configuration variable defined in configure.ac, | |
346 | e.g.: | |
347 | ||
348 | echo "je_cv_madv_free=no" > config.cache && ./configure -C | |
349 | ||
970d7e83 LB |
350 | === Advanced compilation ======================================================= |
351 | ||
352 | To build only parts of jemalloc, use the following targets: | |
353 | ||
354 | build_lib_shared | |
355 | build_lib_static | |
356 | build_lib | |
357 | build_doc_html | |
358 | build_doc_man | |
359 | build_doc | |
360 | ||
361 | To install only parts of jemalloc, use the following targets: | |
362 | ||
363 | install_bin | |
364 | install_include | |
365 | install_lib_shared | |
366 | install_lib_static | |
367 | install_lib | |
368 | install_doc_html | |
369 | install_doc_man | |
370 | install_doc | |
371 | ||
372 | To clean up build results to varying degrees, use the following make targets: | |
373 | ||
374 | clean | |
375 | distclean | |
376 | relclean | |
377 | ||
378 | === Advanced installation ====================================================== | |
379 | ||
380 | Optionally, define make variables when invoking make, including (not | |
381 | exclusively): | |
382 | ||
383 | INCLUDEDIR="?" | |
384 | Use this as the installation prefix for header files. | |
385 | ||
386 | LIBDIR="?" | |
387 | Use this as the installation prefix for libraries. | |
388 | ||
389 | MANDIR="?" | |
390 | Use this as the installation prefix for man pages. | |
391 | ||
392 | DESTDIR="?" | |
393 | Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful | |
394 | when installing to a different path than was specified via --prefix. | |
395 | ||
396 | CC="?" | |
397 | Use this to invoke the C compiler. | |
398 | ||
399 | CFLAGS="?" | |
400 | Pass these flags to the compiler. | |
401 | ||
402 | CPPFLAGS="?" | |
403 | Pass these flags to the C preprocessor. | |
404 | ||
405 | LDFLAGS="?" | |
406 | Pass these flags when linking. | |
407 | ||
408 | PATH="?" | |
409 | Use this to search for programs used during configuration and building. | |
410 | ||
411 | === Development ================================================================ | |
412 | ||
413 | If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' | |
414 | script rather than 'configure'. This re-generates 'configure', enables | |
415 | configuration dependency rules, and enables re-generation of automatically | |
416 | generated source files. | |
417 | ||
418 | The build system supports using an object directory separate from the source | |
419 | tree. For example, you can create an 'obj' directory, and from within that | |
420 | directory, issue configuration and build commands: | |
421 | ||
422 | autoconf | |
423 | mkdir obj | |
424 | cd obj | |
425 | ../configure --enable-autogen | |
426 | make | |
427 | ||
428 | === Documentation ============================================================== | |
429 | ||
430 | The manual page is generated in both html and roff formats. Any web browser | |
431 | can be used to view the html manual. The roff manual page can be formatted | |
432 | prior to installation via the following command: | |
433 | ||
434 | nroff -man -t doc/jemalloc.3 |