michael@0: Building and installing jemalloc can be as simple as typing the following while michael@0: in the root directory of the source tree: michael@0: michael@0: ./configure michael@0: make michael@0: make install michael@0: michael@0: === Advanced configuration ===================================================== michael@0: michael@0: The 'configure' script supports numerous options that allow control of which michael@0: functionality is enabled, where jemalloc is installed, etc. Optionally, pass michael@0: any of the following arguments (not a definitive list) to 'configure': michael@0: michael@0: --help michael@0: Print a definitive list of options. michael@0: michael@0: --prefix= michael@0: Set the base directory in which to install. For example: michael@0: michael@0: ./configure --prefix=/usr/local michael@0: michael@0: will cause files to be installed into /usr/local/include, /usr/local/lib, michael@0: and /usr/local/man. michael@0: michael@0: --with-rpath= michael@0: Embed one or more library paths, so that libjemalloc can find the libraries michael@0: it is linked to. This works only on ELF-based systems. michael@0: michael@0: --with-mangling= michael@0: Mangle public symbols specified in which is a comma-separated list of michael@0: name:mangled pairs. michael@0: michael@0: For example, to use ld's --wrap option as an alternative method for michael@0: overriding libc's malloc implementation, specify something like: michael@0: michael@0: --with-mangling=malloc:__wrap_malloc,free:__wrap_free[...] michael@0: michael@0: Note that mangling happens prior to application of the prefix specified by michael@0: --with-jemalloc-prefix, and mangled symbols are then ignored when applying michael@0: the prefix. michael@0: michael@0: --with-jemalloc-prefix= michael@0: Prefix all public APIs with . For example, if is michael@0: "prefix_", API changes like the following occur: michael@0: michael@0: malloc() --> prefix_malloc() michael@0: malloc_conf --> prefix_malloc_conf michael@0: /etc/malloc.conf --> /etc/prefix_malloc.conf michael@0: MALLOC_CONF --> PREFIX_MALLOC_CONF michael@0: michael@0: This makes it possible to use jemalloc at the same time as the system michael@0: allocator, or even to use multiple copies of jemalloc simultaneously. michael@0: michael@0: By default, the prefix is "", except on OS X, where it is "je_". On OS X, michael@0: jemalloc overlays the default malloc zone, but makes no attempt to actually michael@0: replace the "malloc", "calloc", etc. symbols. michael@0: michael@0: --without-export michael@0: Don't export public APIs. This can be useful when building jemalloc as a michael@0: static library, or to avoid exporting public APIs when using the zone michael@0: allocator on OSX. michael@0: michael@0: --with-private-namespace= michael@0: Prefix all library-private APIs with . For shared libraries, michael@0: symbol visibility mechanisms prevent these symbols from being exported, but michael@0: for static libraries, naming collisions are a real possibility. By michael@0: default, the prefix is "" (empty string). michael@0: michael@0: --with-install-suffix= michael@0: Append to the base name of all installed files, such that multiple michael@0: versions of jemalloc can coexist in the same installation directory. For michael@0: example, libjemalloc.so.0 becomes libjemalloc.so.0. michael@0: michael@0: --enable-cc-silence michael@0: Enable code that silences non-useful compiler warnings. This is helpful michael@0: when trying to tell serious warnings from those due to compiler michael@0: limitations, but it potentially incurs a performance penalty. michael@0: michael@0: --enable-debug michael@0: Enable assertions and validation code. This incurs a substantial michael@0: performance hit, but is very useful during application development. michael@0: michael@0: --disable-stats michael@0: Disable statistics gathering functionality. See the "opt.stats_print" michael@0: option documentation for usage details. michael@0: michael@0: --enable-prof michael@0: Enable heap profiling and leak detection functionality. See the "opt.prof" michael@0: option documentation for usage details. When enabled, there are several michael@0: approaches to backtracing, and the configure script chooses the first one michael@0: in the following list that appears to function correctly: michael@0: michael@0: + libunwind (requires --enable-prof-libunwind) michael@0: + libgcc (unless --disable-prof-libgcc) michael@0: + gcc intrinsics (unless --disable-prof-gcc) michael@0: michael@0: --enable-prof-libunwind michael@0: Use the libunwind library (http://www.nongnu.org/libunwind/) for stack michael@0: backtracing. michael@0: michael@0: --disable-prof-libgcc michael@0: Disable the use of libgcc's backtracing functionality. michael@0: michael@0: --disable-prof-gcc michael@0: Disable the use of gcc intrinsics for backtracing. michael@0: michael@0: --with-static-libunwind= michael@0: Statically link against the specified libunwind.a rather than dynamically michael@0: linking with -lunwind. michael@0: michael@0: --disable-tcache michael@0: Disable thread-specific caches for small objects. Objects are cached and michael@0: released in bulk, thus reducing the total number of mutex operations. See michael@0: the "opt.tcache" option for usage details. michael@0: michael@0: --enable-mremap michael@0: Enable huge realloc() via mremap(2). mremap() is disabled by default michael@0: because the flavor used is specific to Linux, which has a quirk in its michael@0: virtual memory allocation algorithm that causes semi-permanent VM map holes michael@0: under normal jemalloc operation. michael@0: michael@0: --disable-munmap michael@0: Disable virtual memory deallocation via munmap(2); instead keep track of michael@0: the virtual memory for later use. munmap() is disabled by default (i.e. michael@0: --disable-munmap is implied) on Linux, which has a quirk in its virtual michael@0: memory allocation algorithm that causes semi-permanent VM map holes under michael@0: normal jemalloc operation. michael@0: michael@0: --enable-dss michael@0: Enable support for page allocation/deallocation via sbrk(2), in addition to michael@0: mmap(2). michael@0: michael@0: --disable-fill michael@0: Disable support for junk/zero filling of memory, quarantine, and redzones. michael@0: See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option michael@0: documentation for usage details. michael@0: michael@0: --disable-valgrind michael@0: Disable support for Valgrind. michael@0: michael@0: --disable-experimental michael@0: Disable support for the experimental API (*allocm()). michael@0: michael@0: --enable-utrace michael@0: Enable utrace(2)-based allocation tracing. This feature is not broadly michael@0: portable (FreeBSD has it, but Linux and OS X do not). michael@0: michael@0: --enable-xmalloc michael@0: Enable support for optional immediate termination due to out-of-memory michael@0: errors, as is commonly implemented by "xmalloc" wrapper function for malloc. michael@0: See the "opt.xmalloc" option documentation for usage details. michael@0: michael@0: --enable-lazy-lock michael@0: Enable code that wraps pthread_create() to detect when an application michael@0: switches from single-threaded to multi-threaded mode, so that it can avoid michael@0: mutex locking/unlocking operations while in single-threaded mode. In michael@0: practice, this feature usually has little impact on performance unless michael@0: thread-specific caching is disabled. michael@0: michael@0: --disable-tls michael@0: Disable thread-local storage (TLS), which allows for fast access to michael@0: thread-local variables via the __thread keyword. If TLS is available, michael@0: jemalloc uses it for several purposes. michael@0: michael@0: --with-xslroot= michael@0: Specify where to find DocBook XSL stylesheets when building the michael@0: documentation. michael@0: michael@0: The following environment variables (not a definitive list) impact configure's michael@0: behavior: michael@0: michael@0: CFLAGS="?" michael@0: Pass these flags to the compiler. You probably shouldn't define this unless michael@0: you know what you are doing. (Use EXTRA_CFLAGS instead.) michael@0: michael@0: EXTRA_CFLAGS="?" michael@0: Append these flags to CFLAGS. This makes it possible to add flags such as michael@0: -Werror, while allowing the configure script to determine what other flags michael@0: are appropriate for the specified configuration. michael@0: michael@0: The configure script specifically checks whether an optimization flag (-O*) michael@0: is specified in EXTRA_CFLAGS, and refrains from specifying an optimization michael@0: level if it finds that one has already been specified. michael@0: michael@0: CPPFLAGS="?" michael@0: Pass these flags to the C preprocessor. Note that CFLAGS is not passed to michael@0: 'cpp' when 'configure' is looking for include files, so you must use michael@0: CPPFLAGS instead if you need to help 'configure' find header files. michael@0: michael@0: LD_LIBRARY_PATH="?" michael@0: 'ld' uses this colon-separated list to find libraries. michael@0: michael@0: LDFLAGS="?" michael@0: Pass these flags when linking. michael@0: michael@0: PATH="?" michael@0: 'configure' uses this to find programs. michael@0: michael@0: === Advanced compilation ======================================================= michael@0: michael@0: To build only parts of jemalloc, use the following targets: michael@0: michael@0: build_lib_shared michael@0: build_lib_static michael@0: build_lib michael@0: build_doc_html michael@0: build_doc_man michael@0: build_doc michael@0: michael@0: To install only parts of jemalloc, use the following targets: michael@0: michael@0: install_bin michael@0: install_include michael@0: install_lib_shared michael@0: install_lib_static michael@0: install_lib michael@0: install_doc_html michael@0: install_doc_man michael@0: install_doc michael@0: michael@0: To clean up build results to varying degrees, use the following make targets: michael@0: michael@0: clean michael@0: distclean michael@0: relclean michael@0: michael@0: === Advanced installation ====================================================== michael@0: michael@0: Optionally, define make variables when invoking make, including (not michael@0: exclusively): michael@0: michael@0: INCLUDEDIR="?" michael@0: Use this as the installation prefix for header files. michael@0: michael@0: LIBDIR="?" michael@0: Use this as the installation prefix for libraries. michael@0: michael@0: MANDIR="?" michael@0: Use this as the installation prefix for man pages. michael@0: michael@0: DESTDIR="?" michael@0: Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful michael@0: when installing to a different path than was specified via --prefix. michael@0: michael@0: CC="?" michael@0: Use this to invoke the C compiler. michael@0: michael@0: CFLAGS="?" michael@0: Pass these flags to the compiler. michael@0: michael@0: CPPFLAGS="?" michael@0: Pass these flags to the C preprocessor. michael@0: michael@0: LDFLAGS="?" michael@0: Pass these flags when linking. michael@0: michael@0: PATH="?" michael@0: Use this to search for programs used during configuration and building. michael@0: michael@0: === Development ================================================================ michael@0: michael@0: If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' michael@0: script rather than 'configure'. This re-generates 'configure', enables michael@0: configuration dependency rules, and enables re-generation of automatically michael@0: generated source files. michael@0: michael@0: The build system supports using an object directory separate from the source michael@0: tree. For example, you can create an 'obj' directory, and from within that michael@0: directory, issue configuration and build commands: michael@0: michael@0: autoconf michael@0: mkdir obj michael@0: cd obj michael@0: ../configure --enable-autogen michael@0: make michael@0: michael@0: === Documentation ============================================================== michael@0: michael@0: The manual page is generated in both html and roff formats. Any web browser michael@0: can be used to view the html manual. The roff manual page can be formatted michael@0: prior to installation via the following command: michael@0: michael@0: nroff -man -t doc/jemalloc.3