memory/jemalloc/src/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 --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 --enable-cc-silence
  75     Enable code that silences non-useful compiler warnings.  This is helpful
  76     when trying to tell serious warnings from those due to compiler
  77     limitations, but it potentially incurs a performance penalty.
  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 --enable-mremap
 136     Enable huge realloc() via mremap(2).  mremap() is disabled by default
 137     because the flavor used is specific to Linux, which has a quirk in its
 138     virtual memory allocation algorithm that causes semi-permanent VM map holes
 139     under normal jemalloc operation.
 140
 141 --disable-munmap
 142     Disable virtual memory deallocation via munmap(2); instead keep track of
 143     the virtual memory for later use.  munmap() is disabled by default (i.e.
 144     --disable-munmap is implied) on Linux, which has a quirk in its virtual
 145     memory allocation algorithm that causes semi-permanent VM map holes under
 146     normal jemalloc operation.
 147
 148 --enable-dss
 149     Enable support for page allocation/deallocation via sbrk(2), in addition to
 150     mmap(2).
 151
 152 --disable-fill
 153     Disable support for junk/zero filling of memory, quarantine, and redzones.
 154     See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option
 155     documentation for usage details.
 156
 157 --disable-valgrind
 158     Disable support for Valgrind.
 159
 160 --disable-experimental
 161     Disable support for the experimental API (*allocm()).
 162
 163 --disable-zone-allocator
 164     Disable zone allocator for Darwin. This means jemalloc won't be hooked as
 165     the default allocator on OSX/iOS.
 166
 167 --enable-utrace
 168     Enable utrace(2)-based allocation tracing.  This feature is not broadly
 169     portable (FreeBSD has it, but Linux and OS X do not).
 170
 171 --enable-xmalloc
 172     Enable support for optional immediate termination due to out-of-memory
 173     errors, as is commonly implemented by "xmalloc" wrapper function for malloc.
 174     See the "opt.xmalloc" option documentation for usage details.
 175
 176 --enable-lazy-lock
 177     Enable code that wraps pthread_create() to detect when an application
 178     switches from single-threaded to multi-threaded mode, so that it can avoid
 179     mutex locking/unlocking operations while in single-threaded mode.  In
 180     practice, this feature usually has little impact on performance unless
 181     thread-specific caching is disabled.
 182
 183 --disable-tls
 184     Disable thread-local storage (TLS), which allows for fast access to
 185     thread-local variables via the __thread keyword.  If TLS is available,
 186     jemalloc uses it for several purposes.
 187
 188 --with-xslroot=<path>
 189     Specify where to find DocBook XSL stylesheets when building the
 190     documentation.
 191
 192 The following environment variables (not a definitive list) impact configure's
 193 behavior:
 194
 195 CFLAGS="?"
 196     Pass these flags to the compiler.  You probably shouldn't define this unless
 197     you know what you are doing.  (Use EXTRA_CFLAGS instead.)
 198
 199 EXTRA_CFLAGS="?"
 200     Append these flags to CFLAGS.  This makes it possible to add flags such as
 201     -Werror, while allowing the configure script to determine what other flags
 202     are appropriate for the specified configuration.
 203
 204     The configure script specifically checks whether an optimization flag (-O*)
 205     is specified in EXTRA_CFLAGS, and refrains from specifying an optimization
 206     level if it finds that one has already been specified.
 207
 208 CPPFLAGS="?"
 209     Pass these flags to the C preprocessor.  Note that CFLAGS is not passed to
 210     'cpp' when 'configure' is looking for include files, so you must use
 211     CPPFLAGS instead if you need to help 'configure' find header files.
 212
 213 LD_LIBRARY_PATH="?"
 214     'ld' uses this colon-separated list to find libraries.
 215
 216 LDFLAGS="?"
 217     Pass these flags when linking.
 218
 219 PATH="?"
 220     'configure' uses this to find programs.
 221
 222 === Advanced compilation =======================================================
 223
 224 To build only parts of jemalloc, use the following targets:
 225
 226     build_lib_shared
 227     build_lib_static
 228     build_lib
 229     build_doc_html
 230     build_doc_man
 231     build_doc
 232
 233 To install only parts of jemalloc, use the following targets:
 234
 235     install_bin
 236     install_include
 237     install_lib_shared
 238     install_lib_static
 239     install_lib
 240     install_doc_html
 241     install_doc_man
 242     install_doc
 243
 244 To clean up build results to varying degrees, use the following make targets:
 245
 246     clean
 247     distclean
 248     relclean
 249
 250 === Advanced installation ======================================================
 251
 252 Optionally, define make variables when invoking make, including (not
 253 exclusively):
 254
 255 INCLUDEDIR="?"
 256     Use this as the installation prefix for header files.
 257
 258 LIBDIR="?"
 259     Use this as the installation prefix for libraries.
 260
 261 MANDIR="?"
 262     Use this as the installation prefix for man pages.
 263
 264 DESTDIR="?"
 265     Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR.  This is useful
 266     when installing to a different path than was specified via --prefix.
 267
 268 CC="?"
 269     Use this to invoke the C compiler.
 270
 271 CFLAGS="?"
 272     Pass these flags to the compiler.
 273
 274 CPPFLAGS="?"
 275     Pass these flags to the C preprocessor.
 276
 277 LDFLAGS="?"
 278     Pass these flags when linking.
 279
 280 PATH="?"
 281     Use this to search for programs used during configuration and building.
 282
 283 === Development ================================================================
 284
 285 If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
 286 script rather than 'configure'.  This re-generates 'configure', enables
 287 configuration dependency rules, and enables re-generation of automatically
 288 generated source files.
 289
 290 The build system supports using an object directory separate from the source
 291 tree.  For example, you can create an 'obj' directory, and from within that
 292 directory, issue configuration and build commands:
 293
 294     autoconf
 295     mkdir obj
 296     cd obj
 297     ../configure --enable-autogen
 298     make
 299
 300 === Documentation ==============================================================
 301
 302 The manual page is generated in both html and roff formats.  Any web browser
 303 can be used to view the html manual.  The roff manual page can be formatted
 304 prior to installation via the following command:
 305
 306     nroff -man -t doc/jemalloc.3