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-jemalloc-prefix=<prefix>
  30     Prefix all public APIs with <prefix>.  For example, if <prefix> is
  31     "prefix_", API changes like the following occur:
  32
  33       malloc()         --> prefix_malloc()
  34       malloc_conf      --> prefix_malloc_conf
  35       /etc/malloc.conf --> /etc/prefix_malloc.conf
  36       MALLOC_CONF      --> PREFIX_MALLOC_CONF
  37
  38     This makes it possible to use jemalloc at the same time as the system
  39     allocator, or even to use multiple copies of jemalloc simultaneously.
  40
  41     By default, the prefix is "", except on OS X, where it is "je_".  On OS X,
  42     jemalloc overlays the default malloc zone, but makes no attempt to actually
  43     replace the "malloc", "calloc", etc. symbols.
  44
  45 --with-install-suffix=<suffix>
  46     Append <suffix> to the base name of all installed files, such that multiple
  47     versions of jemalloc can coexist in the same installation directory.  For
  48     example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0.
  49
  50 --enable-cc-silence
  51     Enable code that silences non-useful compiler warnings.  This is helpful
  52     when trying to tell serious warnings from those due to compiler
  53     limitations, but it potentially incurs a performance penalty.
  54
  55 --enable-debug
  56     Enable assertions and validation code.  This incurs a substantial
  57     performance hit, but is very useful during application development.
  58
  59 --enable-stats
  60     Enable statistics gathering functionality.  See the "opt.stats_print"
  61     option documentation for usage details.
  62
  63 --enable-prof
  64     Enable heap profiling and leak detection functionality.  See the "opt.prof"
  65     option documentation for usage details.  When enabled, there are several
  66     approaches to backtracing, and the configure script chooses the first one
  67     in the following list that appears to function correctly:
  68
  69     + libunwind      (requires --enable-prof-libunwind)
  70     + libgcc         (unless --disable-prof-libgcc)
  71     + gcc intrinsics (unless --disable-prof-gcc)
  72
  73 --enable-prof-libunwind
  74     Use the libunwind library (http://www.nongnu.org/libunwind/) for stack
  75     backtracing.
  76
  77 --disable-prof-libgcc
  78     Disable the use of libgcc's backtracing functionality.
  79
  80 --disable-prof-gcc
  81     Disable the use of gcc intrinsics for backtracing.
  82
  83 --with-static-libunwind=<libunwind.a>
  84     Statically link against the specified libunwind.a rather than dynamically
  85     linking with -lunwind.
  86
  87 --disable-tiny
  88     Disable tiny (sub-quantum-sized) object support.  Technically it is not
  89     legal for a malloc implementation to allocate objects with less than
  90     quantum alignment (8 or 16 bytes, depending on architecture), but in
  91     practice it never causes any problems if, for example, 4-byte allocations
  92     are 4-byte-aligned.
  93
  94 --disable-tcache
  95     Disable thread-specific caches for small objects.  Objects are cached and
  96     released in bulk, thus reducing the total number of mutex operations.  See
  97     the "opt.tcache" option for usage details.
  98
  99 --enable-swap
 100     Enable mmap()ed swap file support.  When this feature is built in, it is
 101     possible to specify one or more files that act as backing store.  This
 102     effectively allows for per application swap files.
 103
 104 --enable-dss
 105     Enable support for page allocation/deallocation via sbrk(2), in addition to
 106     mmap(2).
 107
 108 --enable-fill
 109     Enable support for junk/zero filling of memory.  See the "opt.junk"/
 110     "opt.zero" option documentation for usage details.
 111
 112 --enable-xmalloc
 113     Enable support for optional immediate termination due to out-of-memory
 114     errors, as is commonly implemented by "xmalloc" wrapper function for malloc.
 115     See the "opt.xmalloc" option documentation for usage details.
 116
 117 --enable-sysv
 118     Enable support for System V semantics, wherein malloc(0) returns NULL
 119     rather than a minimal allocation.  See the "opt.sysv" option documentation
 120     for usage details.
 121
 122 --enable-dynamic-page-shift
 123     Under most conditions, the system page size never changes (usually 4KiB or
 124     8KiB, depending on architecture and configuration), and unless this option
 125     is enabled, jemalloc assumes that page size can safely be determined during
 126     configuration and hard-coded.  Enabling dynamic page size determination has
 127     a measurable impact on performance, since the compiler is forced to load
 128     the page size from memory rather than embedding immediate values.
 129
 130 --disable-lazy-lock
 131     Disable code that wraps pthread_create() to detect when an application
 132     switches from single-threaded to multi-threaded mode, so that it can avoid
 133     mutex locking/unlocking operations while in single-threaded mode.  In
 134     practice, this feature usually has little impact on performance unless
 135     thread-specific caching is disabled.
 136
 137 --disable-tls
 138     Disable thread-local storage (TLS), which allows for fast access to
 139     thread-local variables via the __thread keyword.  If TLS is available,
 140     jemalloc uses it for several purposes.
 141
 142 --with-xslroot=<path>
 143     Specify where to find DocBook XSL stylesheets when building the
 144     documentation.
 145
 146 The following environment variables (not a definitive list) impact configure's
 147 behavior:
 148
 149 CFLAGS="?"
 150     Pass these flags to the compiler.  You probably shouldn't define this unless
 151     you know what you are doing.  (Use EXTRA_CFLAGS instead.)
 152
 153 EXTRA_CFLAGS="?"
 154     Append these flags to CFLAGS.  This makes it possible to add flags such as
 155     -Werror, while allowing the configure script to determine what other flags
 156     are appropriate for the specified configuration.
 157
 158     The configure script specifically checks whether an optimization flag (-O*)
 159     is specified in EXTRA_CFLAGS, and refrains from specifying an optimization
 160     level if it finds that one has already been specified.
 161
 162 CPPFLAGS="?"
 163     Pass these flags to the C preprocessor.  Note that CFLAGS is not passed to
 164     'cpp' when 'configure' is looking for include files, so you must use
 165     CPPFLAGS instead if you need to help 'configure' find header files.
 166
 167 LD_LIBRARY_PATH="?"
 168     'ld' uses this colon-separated list to find libraries.
 169
 170 LDFLAGS="?"
 171     Pass these flags when linking.
 172
 173 PATH="?"
 174     'configure' uses this to find programs.
 175
 176 === Advanced compilation =======================================================
 177
 178 To install only parts of jemalloc, use the following targets:
 179
 180     install_bin
 181     install_include
 182     install_lib
 183     install_doc
 184
 185 To clean up build results to varying degrees, use the following make targets:
 186
 187     clean
 188     distclean
 189     relclean
 190
 191 === Advanced installation ======================================================
 192
 193 Optionally, define make variables when invoking make, including (not
 194 exclusively):
 195
 196 INCLUDEDIR="?"
 197     Use this as the installation prefix for header files.
 198
 199 LIBDIR="?"
 200     Use this as the installation prefix for libraries.
 201
 202 MANDIR="?"
 203     Use this as the installation prefix for man pages.
 204
 205 DESTDIR="?"
 206     Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR.  This is useful
 207     when installing to a different path than was specified via --prefix.
 208
 209 CC="?"
 210     Use this to invoke the C compiler.
 211
 212 CFLAGS="?"
 213     Pass these flags to the compiler.
 214
 215 CPPFLAGS="?"
 216     Pass these flags to the C preprocessor.
 217
 218 LDFLAGS="?"
 219     Pass these flags when linking.
 220
 221 PATH="?"
 222     Use this to search for programs used during configuration and building.
 223
 224 === Development ================================================================
 225
 226 If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
 227 script rather than 'configure'.  This re-generates 'configure', enables
 228 configuration dependency rules, and enables re-generation of automatically
 229 generated source files.
 230
 231 The build system supports using an object directory separate from the source
 232 tree.  For example, you can create an 'obj' directory, and from within that
 233 directory, issue configuration and build commands:
 234
 235     autoconf
 236     mkdir obj
 237     cd obj
 238     ../configure --enable-autogen
 239     make
 240
 241 === Documentation ==============================================================
 242
 243 The manual page is generated in both html and roff formats.  Any web browser
 244 can be used to view the html manual.  The roff manual page can be formatted
 245 prior to installation via any of the following commands:
 246
 247     nroff -man -t doc/jemalloc.3
 248
 249     groff -man -t -Tps doc/jemalloc.3 | ps2pdf - doc/jemalloc.3.pdf
 250
 251     (cd doc; groff -man -man-ext -t -Thtml jemalloc.3 > jemalloc.3.html)