1Building and installing jemalloc can be as simple as typing the following while
2in the root directory of the source tree:
3
4    ./configure
5    make
6    make install
7
8=== Advanced configuration =====================================================
9
10The 'configure' script supports numerous options that allow control of which
11functionality is enabled, where jemalloc is installed, etc.  Optionally, pass
12any 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>
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.
28
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
42--with-jemalloc-prefix=<prefix>
43    Prefix all public APIs with <prefix>.  For example, if <prefix> is
44    "prefix_", API changes like the following occur:
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
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.
53
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
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
63--with-private-namespace=<prefix>
64    Prefix all library-private APIs with <prefix>je_.  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, <prefix> is empty, which results in a symbol prefix of je_ .
68
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
74--disable-cc-silence
75    Disable code that silences non-useful compiler warnings.  This is mainly
76    useful during development when auditing the set of warnings that are being
77    silenced.
78
79--enable-debug
80    Enable assertions and validation code.  This incurs a substantial
81    performance hit, but is very useful during application development.
82    Implies --enable-ivsalloc.
83
84--enable-code-coverage
85    Enable code coverage support, for use during jemalloc test development.
86    Additional testing targets are available if this option is enabled:
87
88      coverage
89      coverage_unit
90      coverage_integration
91      coverage_stress
92
93    These targets do not clear code coverage results from previous runs, and
94    there are interactions between the various coverage targets, so it is
95    usually advisable to run 'make clean' between repeated code coverage runs.
96
97--enable-ivsalloc
98    Enable validation code, which verifies that pointers reside within
99    jemalloc-owned chunks before dereferencing them. This incurs a substantial
100    performance hit.
101
102--disable-stats
103    Disable statistics gathering functionality.  See the "opt.stats_print"
104    option documentation for usage details.
105
106--enable-prof
107    Enable heap profiling and leak detection functionality.  See the "opt.prof"
108    option documentation for usage details.  When enabled, there are several
109    approaches to backtracing, and the configure script chooses the first one
110    in the following list that appears to function correctly:
111
112    + libunwind      (requires --enable-prof-libunwind)
113    + libgcc         (unless --disable-prof-libgcc)
114    + gcc intrinsics (unless --disable-prof-gcc)
115
116--enable-prof-libunwind
117    Use the libunwind library (http://www.nongnu.org/libunwind/) for stack
118    backtracing.
119
120--disable-prof-libgcc
121    Disable the use of libgcc's backtracing functionality.
122
123--disable-prof-gcc
124    Disable the use of gcc intrinsics for backtracing.
125
126--with-static-libunwind=<libunwind.a>
127    Statically link against the specified libunwind.a rather than dynamically
128    linking with -lunwind.
129
130--disable-tcache
131    Disable thread-specific caches for small objects.  Objects are cached and
132    released in bulk, thus reducing the total number of mutex operations.  See
133    the "opt.tcache" option for usage details.
134
135--disable-munmap
136    Disable virtual memory deallocation via munmap(2); instead keep track of
137    the virtual memory for later use.  munmap() is disabled by default (i.e.
138    --disable-munmap is implied) on Linux, which has a quirk in its virtual
139    memory allocation algorithm that causes semi-permanent VM map holes under
140    normal jemalloc operation.
141
142--disable-fill
143    Disable support for junk/zero filling of memory, quarantine, and redzones.
144    See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option
145    documentation for usage details.
146
147--disable-valgrind
148    Disable support for Valgrind.
149
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
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
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.
161    See the "opt.xmalloc" option documentation for usage details.
162
163--enable-lazy-lock
164    Enable code that wraps pthread_create() to detect when an application
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
168    thread-specific caching is disabled.
169
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,
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.
178
179The following environment variables (not a definitive list) impact configure's
180behavior:
181
182CFLAGS="?"
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
186EXTRA_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
195CPPFLAGS="?"
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
200LD_LIBRARY_PATH="?"
201    'ld' uses this colon-separated list to find libraries.
202
203LDFLAGS="?"
204    Pass these flags when linking.
205
206PATH="?"
207    'configure' uses this to find programs.
208
209=== Advanced compilation =======================================================
210
211To 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
220To install only parts of jemalloc, use the following targets:
221
222    install_bin
223    install_include
224    install_lib_shared
225    install_lib_static
226    install_lib
227    install_doc_html
228    install_doc_man
229    install_doc
230
231To clean up build results to varying degrees, use the following make targets:
232
233    clean
234    distclean
235    relclean
236
237=== Advanced installation ======================================================
238
239Optionally, define make variables when invoking make, including (not
240exclusively):
241
242INCLUDEDIR="?"
243    Use this as the installation prefix for header files.
244
245LIBDIR="?"
246    Use this as the installation prefix for libraries.
247
248MANDIR="?"
249    Use this as the installation prefix for man pages.
250
251DESTDIR="?"
252    Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR.  This is useful
253    when installing to a different path than was specified via --prefix.
254
255CC="?"
256    Use this to invoke the C compiler.
257
258CFLAGS="?"
259    Pass these flags to the compiler.
260
261CPPFLAGS="?"
262    Pass these flags to the C preprocessor.
263
264LDFLAGS="?"
265    Pass these flags when linking.
266
267PATH="?"
268    Use this to search for programs used during configuration and building.
269
270=== Development ================================================================
271
272If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
273script rather than 'configure'.  This re-generates 'configure', enables
274configuration dependency rules, and enables re-generation of automatically
275generated source files.
276
277The build system supports using an object directory separate from the source
278tree.  For example, you can create an 'obj' directory, and from within that
279directory, issue configuration and build commands:
280
281    autoconf
282    mkdir obj
283    cd obj
284    ../configure --enable-autogen
285    make
286
287=== Documentation ==============================================================
288
289The manual page is generated in both html and roff formats.  Any web browser
290can be used to view the html manual.  The roff manual page can be formatted
291prior to installation via the following command:
292
293    nroff -man -t doc/jemalloc.3
294