2009-06-26 09:06:48 +08:00
|
|
|
Building and installing jemalloc can be as simple as typing the following while
|
|
|
|
|
in the root directory of the source tree:
|
|
|
|
|
|
|
|
|
|
./configure
|
|
|
|
|
make
|
|
|
|
|
make install
|
|
|
|
|
|
|
|
|
|
=== Advanced configuration =====================================================
|
|
|
|
|
|
|
|
|
|
The 'configure' script supports numerous options that allow control of which
|
|
|
|
|
functionality is enabled, where jemalloc is installed, etc. Optionally, pass
|
|
|
|
|
any of the following arguments (not a definitive list) to 'configure':
|
|
|
|
|
|
|
|
|
|
--help
|
|
|
|
|
Print a definitive list of options.
|
|
|
|
|
|
|
|
|
|
--prefix=<install-root-dir>
|
|
|
|
|
Set the base directory in which to install. For example:
|
|
|
|
|
|
|
|
|
|
./configure --prefix=/usr/local
|
|
|
|
|
|
|
|
|
|
will cause files to be installed into /usr/local/include, /usr/local/lib,
|
|
|
|
|
and /usr/local/man.
|
|
|
|
|
|
|
|
|
|
--with-rpath=<colon-separated-rpath>
|
2009-12-29 16:09:15 +08:00
|
|
|
Embed one or more library paths, so that libjemalloc can find the libraries
|
|
|
|
|
it is linked to. This works only on ELF-based systems.
|
2009-06-26 09:06:48 +08:00
|
|
|
|
2012-03-02 09:19:20 +08:00
|
|
|
--with-mangling=<map>
|
|
|
|
|
Mangle public symbols specified in <map> which is a comma-separated list of
|
|
|
|
|
name:mangled pairs.
|
|
|
|
|
|
|
|
|
|
For example, to use ld's --wrap option as an alternative method for
|
|
|
|
|
overriding libc's malloc implementation, specify something like:
|
|
|
|
|
|
|
|
|
|
--with-mangling=malloc:__wrap_malloc,free:__wrap_free[...]
|
|
|
|
|
|
|
|
|
|
Note that mangling happens prior to application of the prefix specified by
|
|
|
|
|
--with-jemalloc-prefix, and mangled symbols are then ignored when applying
|
|
|
|
|
the prefix.
|
|
|
|
|
|
2009-12-29 16:09:15 +08:00
|
|
|
--with-jemalloc-prefix=<prefix>
|
2010-10-24 09:37:06 +08:00
|
|
|
Prefix all public APIs with <prefix>. For example, if <prefix> is
|
2010-12-17 06:13:46 +08:00
|
|
|
"prefix_", API changes like the following occur:
|
2010-10-24 09:37:06 +08:00
|
|
|
|
|
|
|
|
malloc() --> prefix_malloc()
|
|
|
|
|
malloc_conf --> prefix_malloc_conf
|
|
|
|
|
/etc/malloc.conf --> /etc/prefix_malloc.conf
|
|
|
|
|
MALLOC_CONF --> PREFIX_MALLOC_CONF
|
|
|
|
|
|
2010-10-25 07:18:29 +08:00
|
|
|
This makes it possible to use jemalloc at the same time as the system
|
|
|
|
|
allocator, or even to use multiple copies of jemalloc simultaneously.
|
2009-12-29 16:09:15 +08:00
|
|
|
|
2010-09-06 01:35:13 +08:00
|
|
|
By default, the prefix is "", except on OS X, where it is "je_". On OS X,
|
|
|
|
|
jemalloc overlays the default malloc zone, but makes no attempt to actually
|
|
|
|
|
replace the "malloc", "calloc", etc. symbols.
|
|
|
|
|
|
2012-11-19 17:55:26 +08:00
|
|
|
--without-export
|
|
|
|
|
Don't export public APIs. This can be useful when building jemalloc as a
|
|
|
|
|
static library, or to avoid exporting public APIs when using the zone
|
|
|
|
|
allocator on OSX.
|
|
|
|
|
|
2011-07-31 07:40:52 +08:00
|
|
|
--with-private-namespace=<prefix>
|
Refactor to support more varied testing.
Refactor the test harness to support three types of tests:
- unit: White box unit tests. These tests have full access to all
internal jemalloc library symbols. Though in actuality all symbols
are prefixed by jet_, macro-based name mangling abstracts this away
from test code.
- integration: Black box integration tests. These tests link with
the installable shared jemalloc library, and with the exception of
some utility code and configure-generated macro definitions, they have
no access to jemalloc internals.
- stress: Black box stress tests. These tests link with the installable
shared jemalloc library, as well as with an internal allocator with
symbols prefixed by jet_ (same as for unit tests) that can be used to
allocate data structures that are internal to the test code.
Move existing tests into test/{unit,integration}/ as appropriate.
Split out internal parts of jemalloc_defs.h.in and put them in
jemalloc_internal_defs.h.in. This reduces internals exposure to
applications that #include <jemalloc/jemalloc.h>.
Refactor jemalloc.h header generation so that a single header file
results, and the prototypes can be used to generate jet_ prototypes for
tests. Split jemalloc.h.in into multiple parts (jemalloc_defs.h.in,
jemalloc_macros.h.in, jemalloc_protos.h.in, jemalloc_mangle.h.in) and
use a shell script to generate a unified jemalloc.h at configure time.
Change the default private namespace prefix from "" to "je_".
Add missing private namespace mangling.
Remove hard-coded private_namespace.h. Instead generate it and
private_unnamespace.h from private_symbols.txt. Use similar logic for
public symbols, which aids in name mangling for jet_ symbols.
Add test_warn() and test_fail(). Replace existing exit(1) calls with
test_fail() calls.
2013-12-01 07:25:42 +08:00
|
|
|
Prefix all library-private APIs with <prefix>je_. For shared libraries,
|
2011-07-31 07:40:52 +08:00
|
|
|
symbol visibility mechanisms prevent these symbols from being exported, but
|
|
|
|
|
for static libraries, naming collisions are a real possibility. By
|
Refactor to support more varied testing.
Refactor the test harness to support three types of tests:
- unit: White box unit tests. These tests have full access to all
internal jemalloc library symbols. Though in actuality all symbols
are prefixed by jet_, macro-based name mangling abstracts this away
from test code.
- integration: Black box integration tests. These tests link with
the installable shared jemalloc library, and with the exception of
some utility code and configure-generated macro definitions, they have
no access to jemalloc internals.
- stress: Black box stress tests. These tests link with the installable
shared jemalloc library, as well as with an internal allocator with
symbols prefixed by jet_ (same as for unit tests) that can be used to
allocate data structures that are internal to the test code.
Move existing tests into test/{unit,integration}/ as appropriate.
Split out internal parts of jemalloc_defs.h.in and put them in
jemalloc_internal_defs.h.in. This reduces internals exposure to
applications that #include <jemalloc/jemalloc.h>.
Refactor jemalloc.h header generation so that a single header file
results, and the prototypes can be used to generate jet_ prototypes for
tests. Split jemalloc.h.in into multiple parts (jemalloc_defs.h.in,
jemalloc_macros.h.in, jemalloc_protos.h.in, jemalloc_mangle.h.in) and
use a shell script to generate a unified jemalloc.h at configure time.
Change the default private namespace prefix from "" to "je_".
Add missing private namespace mangling.
Remove hard-coded private_namespace.h. Instead generate it and
private_unnamespace.h from private_symbols.txt. Use similar logic for
public symbols, which aids in name mangling for jet_ symbols.
Add test_warn() and test_fail(). Replace existing exit(1) calls with
test_fail() calls.
2013-12-01 07:25:42 +08:00
|
|
|
default, <prefix> is empty, which results in a symbol prefix of je_ .
|
2011-07-31 07:40:52 +08:00
|
|
|
|
2010-01-17 17:49:20 +08:00
|
|
|
--with-install-suffix=<suffix>
|
|
|
|
|
Append <suffix> to the base name of all installed files, such that multiple
|
|
|
|
|
versions of jemalloc can coexist in the same installation directory. For
|
|
|
|
|
example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0.
|
|
|
|
|
|
2010-09-21 10:20:48 +08:00
|
|
|
--enable-cc-silence
|
2010-12-17 06:13:46 +08:00
|
|
|
Enable code that silences non-useful compiler warnings. This is helpful
|
|
|
|
|
when trying to tell serious warnings from those due to compiler
|
|
|
|
|
limitations, but it potentially incurs a performance penalty.
|
2010-09-21 10:20:48 +08:00
|
|
|
|
2009-06-26 09:06:48 +08:00
|
|
|
--enable-debug
|
|
|
|
|
Enable assertions and validation code. This incurs a substantial
|
|
|
|
|
performance hit, but is very useful during application development.
|
2012-12-07 05:16:26 +08:00
|
|
|
Implies --enable-ivsalloc.
|
|
|
|
|
|
2013-12-07 10:27:33 +08:00
|
|
|
--enable-code-coverage
|
|
|
|
|
Enable code coverage support, for use during jemalloc test development.
|
|
|
|
|
Additional testing targets are available if this option is enabled:
|
|
|
|
|
|
|
|
|
|
coverage
|
|
|
|
|
coverage_unit
|
|
|
|
|
coverage_integration
|
|
|
|
|
coverage_stress
|
|
|
|
|
|
|
|
|
|
These targets do not clear code coverage results from previous runs, and
|
|
|
|
|
there are interactions between the various coverage targets, so it is
|
|
|
|
|
usually advisable to run 'make clean' between repeated code coverage runs.
|
|
|
|
|
|
2012-12-07 05:16:26 +08:00
|
|
|
--enable-ivsalloc
|
|
|
|
|
Enable validation code, which verifies that pointers reside within
|
|
|
|
|
jemalloc-owned chunks before dereferencing them. This incurs a substantial
|
|
|
|
|
performance hit.
|
2009-06-26 09:06:48 +08:00
|
|
|
|
2012-02-29 12:41:16 +08:00
|
|
|
--disable-stats
|
|
|
|
|
Disable statistics gathering functionality. See the "opt.stats_print"
|
2010-10-25 07:18:29 +08:00
|
|
|
option documentation for usage details.
|
2009-06-26 09:06:48 +08:00
|
|
|
|
2010-02-11 02:37:56 +08:00
|
|
|
--enable-prof
|
2010-10-25 07:18:29 +08:00
|
|
|
Enable heap profiling and leak detection functionality. See the "opt.prof"
|
2011-03-16 13:23:12 +08:00
|
|
|
option documentation for usage details. When enabled, there are several
|
|
|
|
|
approaches to backtracing, and the configure script chooses the first one
|
|
|
|
|
in the following list that appears to function correctly:
|
2010-02-11 02:37:56 +08:00
|
|
|
|
2011-03-16 13:23:12 +08:00
|
|
|
+ libunwind (requires --enable-prof-libunwind)
|
|
|
|
|
+ libgcc (unless --disable-prof-libgcc)
|
|
|
|
|
+ gcc intrinsics (unless --disable-prof-gcc)
|
2010-02-11 10:15:53 +08:00
|
|
|
|
2010-02-11 02:37:56 +08:00
|
|
|
--enable-prof-libunwind
|
|
|
|
|
Use the libunwind library (http://www.nongnu.org/libunwind/) for stack
|
2011-03-16 13:23:12 +08:00
|
|
|
backtracing.
|
|
|
|
|
|
|
|
|
|
--disable-prof-libgcc
|
|
|
|
|
Disable the use of libgcc's backtracing functionality.
|
|
|
|
|
|
|
|
|
|
--disable-prof-gcc
|
|
|
|
|
Disable the use of gcc intrinsics for backtracing.
|
2010-02-11 02:37:56 +08:00
|
|
|
|
2010-03-03 06:12:58 +08:00
|
|
|
--with-static-libunwind=<libunwind.a>
|
|
|
|
|
Statically link against the specified libunwind.a rather than dynamically
|
|
|
|
|
linking with -lunwind.
|
|
|
|
|
|
2009-12-29 16:09:15 +08:00
|
|
|
--disable-tcache
|
2010-03-18 07:27:39 +08:00
|
|
|
Disable thread-specific caches for small objects. Objects are cached and
|
2010-10-25 07:18:29 +08:00
|
|
|
released in bulk, thus reducing the total number of mutex operations. See
|
2010-12-17 06:13:46 +08:00
|
|
|
the "opt.tcache" option for usage details.
|
2009-06-26 09:06:48 +08:00
|
|
|
|
2012-05-10 07:12:00 +08:00
|
|
|
--enable-mremap
|
|
|
|
|
Enable huge realloc() via mremap(2). mremap() is disabled by default
|
|
|
|
|
because the flavor used is specific to Linux, which has a quirk in its
|
|
|
|
|
virtual memory allocation algorithm that causes semi-permanent VM map holes
|
|
|
|
|
under normal jemalloc operation.
|
|
|
|
|
|
2012-04-17 08:52:27 +08:00
|
|
|
--disable-munmap
|
|
|
|
|
Disable virtual memory deallocation via munmap(2); instead keep track of
|
|
|
|
|
the virtual memory for later use. munmap() is disabled by default (i.e.
|
|
|
|
|
--disable-munmap is implied) on Linux, which has a quirk in its virtual
|
|
|
|
|
memory allocation algorithm that causes semi-permanent VM map holes under
|
|
|
|
|
normal jemalloc operation.
|
|
|
|
|
|
2009-06-26 09:06:48 +08:00
|
|
|
--enable-dss
|
|
|
|
|
Enable support for page allocation/deallocation via sbrk(2), in addition to
|
|
|
|
|
mmap(2).
|
|
|
|
|
|
2012-02-29 12:49:22 +08:00
|
|
|
--disable-fill
|
2012-04-06 15:35:09 +08:00
|
|
|
Disable support for junk/zero filling of memory, quarantine, and redzones.
|
|
|
|
|
See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option
|
|
|
|
|
documentation for usage details.
|
|
|
|
|
|
|
|
|
|
--disable-valgrind
|
|
|
|
|
Disable support for Valgrind.
|
2009-06-26 09:06:48 +08:00
|
|
|
|
2012-03-03 09:47:37 +08:00
|
|
|
--disable-experimental
|
|
|
|
|
Disable support for the experimental API (*allocm()).
|
|
|
|
|
|
2012-11-27 01:52:41 +08:00
|
|
|
--disable-zone-allocator
|
|
|
|
|
Disable zone allocator for Darwin. This means jemalloc won't be hooked as
|
|
|
|
|
the default allocator on OSX/iOS.
|
|
|
|
|
|
2012-04-06 04:36:17 +08:00
|
|
|
--enable-utrace
|
|
|
|
|
Enable utrace(2)-based allocation tracing. This feature is not broadly
|
|
|
|
|
portable (FreeBSD has it, but Linux and OS X do not).
|
|
|
|
|
|
2009-06-26 09:06:48 +08:00
|
|
|
--enable-xmalloc
|
|
|
|
|
Enable support for optional immediate termination due to out-of-memory
|
|
|
|
|
errors, as is commonly implemented by "xmalloc" wrapper function for malloc.
|
2010-10-25 07:18:29 +08:00
|
|
|
See the "opt.xmalloc" option documentation for usage details.
|
2009-06-26 09:06:48 +08:00
|
|
|
|
2012-02-14 04:36:11 +08:00
|
|
|
--enable-lazy-lock
|
|
|
|
|
Enable code that wraps pthread_create() to detect when an application
|
2009-06-26 09:06:48 +08:00
|
|
|
switches from single-threaded to multi-threaded mode, so that it can avoid
|
|
|
|
|
mutex locking/unlocking operations while in single-threaded mode. In
|
|
|
|
|
practice, this feature usually has little impact on performance unless
|
2009-12-29 16:09:15 +08:00
|
|
|
thread-specific caching is disabled.
|
2009-06-26 09:06:48 +08:00
|
|
|
|
2010-01-18 06:06:20 +08:00
|
|
|
--disable-tls
|
|
|
|
|
Disable thread-local storage (TLS), which allows for fast access to
|
|
|
|
|
thread-local variables via the __thread keyword. If TLS is available,
|
2010-11-25 14:00:02 +08:00
|
|
|
jemalloc uses it for several purposes.
|
|
|
|
|
|
|
|
|
|
--with-xslroot=<path>
|
|
|
|
|
Specify where to find DocBook XSL stylesheets when building the
|
|
|
|
|
documentation.
|
2010-01-18 06:06:20 +08:00
|
|
|
|
2009-06-26 09:06:48 +08:00
|
|
|
The following environment variables (not a definitive list) impact configure's
|
|
|
|
|
behavior:
|
|
|
|
|
|
|
|
|
|
CFLAGS="?"
|
|
|
|
|
Pass these flags to the compiler. You probably shouldn't define this unless
|
|
|
|
|
you know what you are doing. (Use EXTRA_CFLAGS instead.)
|
|
|
|
|
|
|
|
|
|
EXTRA_CFLAGS="?"
|
|
|
|
|
Append these flags to CFLAGS. This makes it possible to add flags such as
|
|
|
|
|
-Werror, while allowing the configure script to determine what other flags
|
|
|
|
|
are appropriate for the specified configuration.
|
|
|
|
|
|
|
|
|
|
The configure script specifically checks whether an optimization flag (-O*)
|
|
|
|
|
is specified in EXTRA_CFLAGS, and refrains from specifying an optimization
|
|
|
|
|
level if it finds that one has already been specified.
|
|
|
|
|
|
|
|
|
|
CPPFLAGS="?"
|
|
|
|
|
Pass these flags to the C preprocessor. Note that CFLAGS is not passed to
|
|
|
|
|
'cpp' when 'configure' is looking for include files, so you must use
|
|
|
|
|
CPPFLAGS instead if you need to help 'configure' find header files.
|
|
|
|
|
|
|
|
|
|
LD_LIBRARY_PATH="?"
|
|
|
|
|
'ld' uses this colon-separated list to find libraries.
|
|
|
|
|
|
|
|
|
|
LDFLAGS="?"
|
|
|
|
|
Pass these flags when linking.
|
|
|
|
|
|
|
|
|
|
PATH="?"
|
|
|
|
|
'configure' uses this to find programs.
|
|
|
|
|
|
|
|
|
|
=== Advanced compilation =======================================================
|
|
|
|
|
|
2012-03-03 08:38:37 +08:00
|
|
|
To build only parts of jemalloc, use the following targets:
|
|
|
|
|
|
|
|
|
|
build_lib_shared
|
|
|
|
|
build_lib_static
|
|
|
|
|
build_lib
|
|
|
|
|
build_doc_html
|
|
|
|
|
build_doc_man
|
|
|
|
|
build_doc
|
|
|
|
|
|
2010-03-04 07:48:20 +08:00
|
|
|
To install only parts of jemalloc, use the following targets:
|
2009-06-26 09:06:48 +08:00
|
|
|
|
2010-04-12 10:02:43 +08:00
|
|
|
install_bin
|
2010-03-04 07:48:20 +08:00
|
|
|
install_include
|
2012-03-03 08:38:37 +08:00
|
|
|
install_lib_shared
|
|
|
|
|
install_lib_static
|
2010-03-04 07:48:20 +08:00
|
|
|
install_lib
|
2012-03-03 08:38:37 +08:00
|
|
|
install_doc_html
|
|
|
|
|
install_doc_man
|
2010-11-25 14:00:02 +08:00
|
|
|
install_doc
|
2009-06-26 09:06:48 +08:00
|
|
|
|
|
|
|
|
To clean up build results to varying degrees, use the following make targets:
|
|
|
|
|
|
|
|
|
|
clean
|
|
|
|
|
distclean
|
|
|
|
|
relclean
|
|
|
|
|
|
|
|
|
|
=== Advanced installation ======================================================
|
|
|
|
|
|
|
|
|
|
Optionally, define make variables when invoking make, including (not
|
|
|
|
|
exclusively):
|
|
|
|
|
|
|
|
|
|
INCLUDEDIR="?"
|
|
|
|
|
Use this as the installation prefix for header files.
|
|
|
|
|
|
|
|
|
|
LIBDIR="?"
|
|
|
|
|
Use this as the installation prefix for libraries.
|
|
|
|
|
|
|
|
|
|
MANDIR="?"
|
|
|
|
|
Use this as the installation prefix for man pages.
|
|
|
|
|
|
2010-03-04 07:48:20 +08:00
|
|
|
DESTDIR="?"
|
2010-12-17 06:13:46 +08:00
|
|
|
Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful
|
|
|
|
|
when installing to a different path than was specified via --prefix.
|
2010-03-04 07:48:20 +08:00
|
|
|
|
2009-06-26 09:06:48 +08:00
|
|
|
CC="?"
|
|
|
|
|
Use this to invoke the C compiler.
|
|
|
|
|
|
|
|
|
|
CFLAGS="?"
|
|
|
|
|
Pass these flags to the compiler.
|
|
|
|
|
|
|
|
|
|
CPPFLAGS="?"
|
|
|
|
|
Pass these flags to the C preprocessor.
|
|
|
|
|
|
|
|
|
|
LDFLAGS="?"
|
|
|
|
|
Pass these flags when linking.
|
|
|
|
|
|
|
|
|
|
PATH="?"
|
|
|
|
|
Use this to search for programs used during configuration and building.
|
|
|
|
|
|
|
|
|
|
=== Development ================================================================
|
|
|
|
|
|
|
|
|
|
If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
|
|
|
|
|
script rather than 'configure'. This re-generates 'configure', enables
|
|
|
|
|
configuration dependency rules, and enables re-generation of automatically
|
|
|
|
|
generated source files.
|
|
|
|
|
|
|
|
|
|
The build system supports using an object directory separate from the source
|
|
|
|
|
tree. For example, you can create an 'obj' directory, and from within that
|
|
|
|
|
directory, issue configuration and build commands:
|
|
|
|
|
|
|
|
|
|
autoconf
|
|
|
|
|
mkdir obj
|
|
|
|
|
cd obj
|
|
|
|
|
../configure --enable-autogen
|
|
|
|
|
make
|
2010-09-12 13:47:39 +08:00
|
|
|
|
|
|
|
|
=== Documentation ==============================================================
|
|
|
|
|
|
2010-11-25 14:00:02 +08:00
|
|
|
The manual page is generated in both html and roff formats. Any web browser
|
|
|
|
|
can be used to view the html manual. The roff manual page can be formatted
|
2012-04-24 03:49:23 +08:00
|
|
|
prior to installation via the following command:
|
2010-09-12 13:47:39 +08:00
|
|
|
|
2010-11-25 14:00:02 +08:00
|
|
|
nroff -man -t doc/jemalloc.3
|
