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