deps/jemalloc/INSTALL

   1 Building and installing jemalloc can be as simple as typing the following while
   2 in the root directory of the source tree:
   3
   4     ./configure
   5     make
   6     make install
   7
   8 === Advanced configuration =====================================================
   9
  10 The 'configure' script supports numerous options that allow control of which
  11 functionality is enabled, where jemalloc is installed, etc.  Optionally, pass
  12 any 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 --with-private-namespace=<prefix>
  59     Prefix all library-private APIs with <prefix>.  For shared libraries,
  60     symbol visibility mechanisms prevent these symbols from being exported, but
  61     for static libraries, naming collisions are a real possibility.  By
  62     default, the prefix is "" (empty string).
  63
  64 --with-install-suffix=<suffix>
  65     Append <suffix> to the base name of all installed files, such that multiple
  66     versions of jemalloc can coexist in the same installation directory.  For
  67     example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0.
  68
  69 --enable-cc-silence
  70     Enable code that silences non-useful compiler warnings.  This is helpful
  71     when trying to tell serious warnings from those due to compiler
  72     limitations, but it potentially incurs a performance penalty.
  73
  74 --enable-debug
  75     Enable assertions and validation code.  This incurs a substantial
  76     performance hit, but is very useful during application development.
  77
  78 --disable-stats
  79     Disable statistics gathering functionality.  See the "opt.stats_print"
  80     option documentation for usage details.
  81
  82 --enable-prof
  83     Enable heap profiling and leak detection functionality.  See the "opt.prof"
  84     option documentation for usage details.  When enabled, there are several
  85     approaches to backtracing, and the configure script chooses the first one
  86     in the following list that appears to function correctly:
  87
  88     + libunwind      (requires --enable-prof-libunwind)
  89     + libgcc         (unless --disable-prof-libgcc)
  90     + gcc intrinsics (unless --disable-prof-gcc)
  91
  92 --enable-prof-libunwind
  93     Use the libunwind library (http://www.nongnu.org/libunwind/) for stack
  94     backtracing.
  95
  96 --disable-prof-libgcc
  97     Disable the use of libgcc's backtracing functionality.
  98
  99 --disable-prof-gcc
 100     Disable the use of gcc intrinsics for backtracing.
 101
 102 --with-static-libunwind=<libunwind.a>
 103     Statically link against the specified libunwind.a rather than dynamically
 104     linking with -lunwind.
 105
 106 --disable-tcache
 107     Disable thread-specific caches for small objects.  Objects are cached and
 108     released in bulk, thus reducing the total number of mutex operations.  See
 109     the "opt.tcache" option for usage details.
 110
 111 --enable-mremap
 112     Enable huge realloc() via mremap(2).  mremap() is disabled by default
 113     because the flavor used is specific to Linux, which has a quirk in its
 114     virtual memory allocation algorithm that causes semi-permanent VM map holes
 115     under normal jemalloc operation.
 116
 117 --disable-munmap
 118     Disable virtual memory deallocation via munmap(2); instead keep track of
 119     the virtual memory for later use.  munmap() is disabled by default (i.e.
 120     --disable-munmap is implied) on Linux, which has a quirk in its virtual
 121     memory allocation algorithm that causes semi-permanent VM map holes under
 122     normal jemalloc operation.
 123
 124 --enable-dss
 125     Enable support for page allocation/deallocation via sbrk(2), in addition to
 126     mmap(2).
 127
 128 --disable-fill
 129     Disable support for junk/zero filling of memory, quarantine, and redzones.
 130     See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option
 131     documentation for usage details.
 132
 133 --disable-valgrind
 134     Disable support for Valgrind.
 135
 136 --disable-experimental
 137     Disable support for the experimental API (*allocm()).
 138
 139 --enable-utrace
 140     Enable utrace(2)-based allocation tracing.  This feature is not broadly
 141     portable (FreeBSD has it, but Linux and OS X do not).
 142
 143 --enable-xmalloc
 144     Enable support for optional immediate termination due to out-of-memory
 145     errors, as is commonly implemented by "xmalloc" wrapper function for malloc.
 146     See the "opt.xmalloc" option documentation for usage details.
 147
 148 --enable-lazy-lock
 149     Enable code that wraps pthread_create() to detect when an application
 150     switches from single-threaded to multi-threaded mode, so that it can avoid
 151     mutex locking/unlocking operations while in single-threaded mode.  In
 152     practice, this feature usually has little impact on performance unless
 153     thread-specific caching is disabled.
 154
 155 --disable-tls
 156     Disable thread-local storage (TLS), which allows for fast access to
 157     thread-local variables via the __thread keyword.  If TLS is available,
 158     jemalloc uses it for several purposes.
 159
 160 --with-xslroot=<path>
 161     Specify where to find DocBook XSL stylesheets when building the
 162     documentation.
 163
 164 The following environment variables (not a definitive list) impact configure's
 165 behavior:
 166
 167 CFLAGS="?"
 168     Pass these flags to the compiler.  You probably shouldn't define this unless
 169     you know what you are doing.  (Use EXTRA_CFLAGS instead.)
 170
 171 EXTRA_CFLAGS="?"
 172     Append these flags to CFLAGS.  This makes it possible to add flags such as
 173     -Werror, while allowing the configure script to determine what other flags
 174     are appropriate for the specified configuration.
 175
 176     The configure script specifically checks whether an optimization flag (-O*)
 177     is specified in EXTRA_CFLAGS, and refrains from specifying an optimization
 178     level if it finds that one has already been specified.
 179
 180 CPPFLAGS="?"
 181     Pass these flags to the C preprocessor.  Note that CFLAGS is not passed to
 182     'cpp' when 'configure' is looking for include files, so you must use
 183     CPPFLAGS instead if you need to help 'configure' find header files.
 184
 185 LD_LIBRARY_PATH="?"
 186     'ld' uses this colon-separated list to find libraries.
 187
 188 LDFLAGS="?"
 189     Pass these flags when linking.
 190
 191 PATH="?"
 192     'configure' uses this to find programs.
 193
 194 === Advanced compilation =======================================================
 195
 196 To build only parts of jemalloc, use the following targets:
 197
 198     build_lib_shared
 199     build_lib_static
 200     build_lib
 201     build_doc_html
 202     build_doc_man
 203     build_doc
 204
 205 To install only parts of jemalloc, use the following targets:
 206
 207     install_bin
 208     install_include
 209     install_lib_shared
 210     install_lib_static
 211     install_lib
 212     install_doc_html
 213     install_doc_man
 214     install_doc
 215
 216 To clean up build results to varying degrees, use the following make targets:
 217
 218     clean
 219     distclean
 220     relclean
 221
 222 === Advanced installation ======================================================
 223
 224 Optionally, define make variables when invoking make, including (not
 225 exclusively):
 226
 227 INCLUDEDIR="?"
 228     Use this as the installation prefix for header files.
 229
 230 LIBDIR="?"
 231     Use this as the installation prefix for libraries.
 232
 233 MANDIR="?"
 234     Use this as the installation prefix for man pages.
 235
 236 DESTDIR="?"
 237     Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR.  This is useful
 238     when installing to a different path than was specified via --prefix.
 239
 240 CC="?"
 241     Use this to invoke the C compiler.
 242
 243 CFLAGS="?"
 244     Pass these flags to the compiler.
 245
 246 CPPFLAGS="?"
 247     Pass these flags to the C preprocessor.
 248
 249 LDFLAGS="?"
 250     Pass these flags when linking.
 251
 252 PATH="?"
 253     Use this to search for programs used during configuration and building.
 254
 255 === Development ================================================================
 256
 257 If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
 258 script rather than 'configure'.  This re-generates 'configure', enables
 259 configuration dependency rules, and enables re-generation of automatically
 260 generated source files.
 261
 262 The build system supports using an object directory separate from the source
 263 tree.  For example, you can create an 'obj' directory, and from within that
 264 directory, issue configuration and build commands:
 265
 266     autoconf
 267     mkdir obj
 268     cd obj
 269     ../configure --enable-autogen
 270     make
 271
 272 === Documentation ==============================================================
 273
 274 The manual page is generated in both html and roff formats.  Any web browser
 275 can be used to view the html manual.  The roff manual page can be formatted
 276 prior to installation via the following command:
 277
 278     nroff -man -t doc/jemalloc.3