• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Building and installing a packaged release of jemalloc can be as simple as
2typing the following while in the root directory of the source tree:
3
4    ./configure
5    make
6    make install
7
8If building from unpackaged developer sources, the simplest command sequence
9that might work is:
10
11    ./autogen.sh
12    make dist
13    make
14    make install
15
16Note that documentation is not built by the default target because doing so
17would create a dependency on xsltproc in packaged releases, hence the
18requirement to either run 'make dist' or avoid installing docs via the various
19install_* targets documented below.
20
21=== Advanced configuration =====================================================
22
23The 'configure' script supports numerous options that allow control of which
24functionality is enabled, where jemalloc is installed, etc.  Optionally, pass
25any 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
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
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
76    Don't export public APIs.  This can be useful when building jemalloc as a
77    static library, or to avoid exporting public APIs when using the zone
78    allocator on OSX.
79
80--with-private-namespace=<prefix>
81    Prefix all library-private APIs with <prefix>je_.  For shared libraries,
82    symbol visibility mechanisms prevent these symbols from being exported, but
83    for static libraries, naming collisions are a real possibility.  By
84    default, <prefix> is empty, which results in a symbol prefix of je_ .
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
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
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.
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
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
122--disable-stats
123    Disable statistics gathering functionality.  See the "opt.stats_print"
124    option documentation for usage details.
125
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
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
160--disable-munmap
161    Disable virtual memory deallocation via munmap(2); instead keep track of
162    the virtual memory for later use.  munmap() is disabled by default (i.e.
163    --disable-munmap is implied) on Linux, which has a quirk in its virtual
164    memory allocation algorithm that causes semi-permanent VM map holes under
165    normal jemalloc operation.
166
167--disable-fill
168    Disable support for junk/zero filling of memory, quarantine, and redzones.
169    See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option
170    documentation for usage details.
171
172--disable-valgrind
173    Disable support for Valgrind.
174
175--disable-zone-allocator
176    Disable zone allocator for Darwin.  This means jemalloc won't be hooked as
177    the default allocator on OSX/iOS.
178
179--enable-utrace
180    Enable utrace(2)-based allocation tracing.  This feature is not broadly
181    portable (FreeBSD has it, but Linux and OS X do not).
182
183--enable-xmalloc
184    Enable support for optional immediate termination due to out-of-memory
185    errors, as is commonly implemented by "xmalloc" wrapper function for malloc.
186    See the "opt.xmalloc" option documentation for usage details.
187
188--enable-lazy-lock
189    Enable code that wraps pthread_create() to detect when an application
190    switches from single-threaded to multi-threaded mode, so that it can avoid
191    mutex locking/unlocking operations while in single-threaded mode.  In
192    practice, this feature usually has little impact on performance unless
193    thread-specific caching is disabled.
194
195--disable-tls
196    Disable thread-local storage (TLS), which allows for fast access to
197    thread-local variables via the __thread keyword.  If TLS is available,
198    jemalloc uses it for several purposes.
199
200--disable-cache-oblivious
201    Disable cache-oblivious large allocation alignment for large allocation
202    requests with no alignment constraints.  If this feature is disabled, all
203    large allocations are page-aligned as an implementation artifact, which can
204    severely harm CPU cache utilization.  However, the cache-oblivious layout
205    comes at the cost of one extra page per large allocation, which in the
206    most extreme case increases physical memory usage for the 16 KiB size class
207    to 20 KiB.
208
209--disable-syscall
210    Disable use of syscall(2) rather than {open,read,write,close}(2).  This is
211    intended as a workaround for systems that place security limitations on
212    syscall(2).
213
214--with-xslroot=<path>
215    Specify where to find DocBook XSL stylesheets when building the
216    documentation.
217
218--with-lg-page=<lg-page>
219    Specify the base 2 log of the system page size.  This option is only useful
220    when cross compiling, since the configure script automatically determines
221    the host's page size by default.
222
223--with-lg-page-sizes=<lg-page-sizes>
224    Specify the comma-separated base 2 logs of the page sizes to support.  This
225    option may be useful when cross-compiling in combination with
226    --with-lg-page, but its primary use case is for integration with FreeBSD's
227    libc, wherein jemalloc is embedded.
228
229--with-lg-size-class-group=<lg-size-class-group>
230    Specify the base 2 log of how many size classes to use for each doubling in
231    size.  By default jemalloc uses <lg-size-class-group>=2, which results in
232    e.g. the following size classes:
233
234      [...], 64,
235      80, 96, 112, 128,
236      160, [...]
237
238    <lg-size-class-group>=3 results in e.g. the following size classes:
239
240      [...], 64,
241      72, 80, 88, 96, 104, 112, 120, 128,
242      144, [...]
243
244    The minimal <lg-size-class-group>=0 causes jemalloc to only provide size
245    classes that are powers of 2:
246
247      [...],
248      64,
249      128,
250      256,
251      [...]
252
253    An implementation detail currently limits the total number of small size
254    classes to 255, and a compilation error will result if the
255    <lg-size-class-group> you specify cannot be supported.  The limit is
256    roughly <lg-size-class-group>=4, depending on page size.
257
258--with-lg-quantum=<lg-quantum>
259    Specify the base 2 log of the minimum allocation alignment.  jemalloc needs
260    to know the minimum alignment that meets the following C standard
261    requirement (quoted from the April 12, 2011 draft of the C11 standard):
262
263      The pointer returned if the allocation succeeds is suitably aligned so
264      that it may be assigned to a pointer to any type of object with a
265      fundamental alignment requirement and then used to access such an object
266      or an array of such objects in the space allocated [...]
267
268    This setting is architecture-specific, and although jemalloc includes known
269    safe values for the most commonly used modern architectures, there is a
270    wrinkle related to GNU libc (glibc) that may impact your choice of
271    <lg-quantum>.  On most modern architectures, this mandates 16-byte alignment
272    (<lg-quantum>=4), but the glibc developers chose not to meet this
273    requirement for performance reasons.  An old discussion can be found at
274    https://sourceware.org/bugzilla/show_bug.cgi?id=206 .  Unlike glibc,
275    jemalloc does follow the C standard by default (caveat: jemalloc
276    technically cheats if --with-lg-tiny-min is smaller than
277    --with-lg-quantum), but the fact that Linux systems already work around
278    this allocator noncompliance means that it is generally safe in practice to
279    let jemalloc's minimum alignment follow glibc's lead.  If you specify
280    --with-lg-quantum=3 during configuration, jemalloc will provide additional
281    size classes that are not 16-byte-aligned (24, 40, and 56, assuming
282    --with-lg-size-class-group=2).
283
284--with-lg-tiny-min=<lg-tiny-min>
285    Specify the base 2 log of the minimum tiny size class to support.  Tiny
286    size classes are powers of 2 less than the quantum, and are only
287    incorporated if <lg-tiny-min> is less than <lg-quantum> (see
288    --with-lg-quantum).  Tiny size classes technically violate the C standard
289    requirement for minimum alignment, and crashes could conceivably result if
290    the compiler were to generate instructions that made alignment assumptions,
291    both because illegal instruction traps could result, and because accesses
292    could straddle page boundaries and cause segmentation faults due to
293    accessing unmapped addresses.
294
295    The default of <lg-tiny-min>=3 works well in practice even on architectures
296    that technically require 16-byte alignment, probably for the same reason
297    --with-lg-quantum=3 works.  Smaller tiny size classes can, and will, cause
298    crashes (see https://bugzilla.mozilla.org/show_bug.cgi?id=691003 for an
299    example).
300
301    This option is rarely useful, and is mainly provided as documentation of a
302    subtle implementation detail.  If you do use this option, specify a
303    value in [3, ..., <lg-quantum>].
304
305The following environment variables (not a definitive list) impact configure's
306behavior:
307
308CFLAGS="?"
309    Pass these flags to the compiler.  You probably shouldn't define this unless
310    you know what you are doing.  (Use EXTRA_CFLAGS instead.)
311
312EXTRA_CFLAGS="?"
313    Append these flags to CFLAGS.  This makes it possible to add flags such as
314    -Werror, while allowing the configure script to determine what other flags
315    are appropriate for the specified configuration.
316
317    The configure script specifically checks whether an optimization flag (-O*)
318    is specified in EXTRA_CFLAGS, and refrains from specifying an optimization
319    level if it finds that one has already been specified.
320
321CPPFLAGS="?"
322    Pass these flags to the C preprocessor.  Note that CFLAGS is not passed to
323    'cpp' when 'configure' is looking for include files, so you must use
324    CPPFLAGS instead if you need to help 'configure' find header files.
325
326LD_LIBRARY_PATH="?"
327    'ld' uses this colon-separated list to find libraries.
328
329LDFLAGS="?"
330    Pass these flags when linking.
331
332PATH="?"
333    'configure' uses this to find programs.
334
335In some cases it may be necessary to work around configuration results that do
336not match reality.  For example, Linux 4.5 added support for the MADV_FREE flag
337to madvise(2), which can cause problems if building on a host with MADV_FREE
338support and deploying to a target without.  To work around this, use a cache
339file to override the relevant configuration variable defined in configure.ac,
340e.g.:
341
342    echo "je_cv_madv_free=no" > config.cache && ./configure -C
343
344=== Advanced compilation =======================================================
345
346To build only parts of jemalloc, use the following targets:
347
348    build_lib_shared
349    build_lib_static
350    build_lib
351    build_doc_html
352    build_doc_man
353    build_doc
354
355To install only parts of jemalloc, use the following targets:
356
357    install_bin
358    install_include
359    install_lib_shared
360    install_lib_static
361    install_lib
362    install_doc_html
363    install_doc_man
364    install_doc
365
366To clean up build results to varying degrees, use the following make targets:
367
368    clean
369    distclean
370    relclean
371
372=== Advanced installation ======================================================
373
374Optionally, define make variables when invoking make, including (not
375exclusively):
376
377INCLUDEDIR="?"
378    Use this as the installation prefix for header files.
379
380LIBDIR="?"
381    Use this as the installation prefix for libraries.
382
383MANDIR="?"
384    Use this as the installation prefix for man pages.
385
386DESTDIR="?"
387    Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR.  This is useful
388    when installing to a different path than was specified via --prefix.
389
390CC="?"
391    Use this to invoke the C compiler.
392
393CFLAGS="?"
394    Pass these flags to the compiler.
395
396CPPFLAGS="?"
397    Pass these flags to the C preprocessor.
398
399LDFLAGS="?"
400    Pass these flags when linking.
401
402PATH="?"
403    Use this to search for programs used during configuration and building.
404
405=== Development ================================================================
406
407If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
408script rather than 'configure'.  This re-generates 'configure', enables
409configuration dependency rules, and enables re-generation of automatically
410generated source files.
411
412The build system supports using an object directory separate from the source
413tree.  For example, you can create an 'obj' directory, and from within that
414directory, issue configuration and build commands:
415
416    autoconf
417    mkdir obj
418    cd obj
419    ../configure --enable-autogen
420    make
421
422=== Documentation ==============================================================
423
424The manual page is generated in both html and roff formats.  Any web browser
425can be used to view the html manual.  The roff manual page can be formatted
426prior to installation via the following command:
427
428    nroff -man -t doc/jemalloc.3
429