1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/memory/jemalloc/src/INSTALL Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,283 @@
1.4 +Building and installing jemalloc can be as simple as typing the following while
1.5 +in the root directory of the source tree:
1.6 +
1.7 + ./configure
1.8 + make
1.9 + make install
1.10 +
1.11 +=== Advanced configuration =====================================================
1.12 +
1.13 +The 'configure' script supports numerous options that allow control of which
1.14 +functionality is enabled, where jemalloc is installed, etc. Optionally, pass
1.15 +any of the following arguments (not a definitive list) to 'configure':
1.16 +
1.17 +--help
1.18 + Print a definitive list of options.
1.19 +
1.20 +--prefix=<install-root-dir>
1.21 + Set the base directory in which to install. For example:
1.22 +
1.23 + ./configure --prefix=/usr/local
1.24 +
1.25 + will cause files to be installed into /usr/local/include, /usr/local/lib,
1.26 + and /usr/local/man.
1.27 +
1.28 +--with-rpath=<colon-separated-rpath>
1.29 + Embed one or more library paths, so that libjemalloc can find the libraries
1.30 + it is linked to. This works only on ELF-based systems.
1.31 +
1.32 +--with-mangling=<map>
1.33 + Mangle public symbols specified in <map> which is a comma-separated list of
1.34 + name:mangled pairs.
1.35 +
1.36 + For example, to use ld's --wrap option as an alternative method for
1.37 + overriding libc's malloc implementation, specify something like:
1.38 +
1.39 + --with-mangling=malloc:__wrap_malloc,free:__wrap_free[...]
1.40 +
1.41 + Note that mangling happens prior to application of the prefix specified by
1.42 + --with-jemalloc-prefix, and mangled symbols are then ignored when applying
1.43 + the prefix.
1.44 +
1.45 +--with-jemalloc-prefix=<prefix>
1.46 + Prefix all public APIs with <prefix>. For example, if <prefix> is
1.47 + "prefix_", API changes like the following occur:
1.48 +
1.49 + malloc() --> prefix_malloc()
1.50 + malloc_conf --> prefix_malloc_conf
1.51 + /etc/malloc.conf --> /etc/prefix_malloc.conf
1.52 + MALLOC_CONF --> PREFIX_MALLOC_CONF
1.53 +
1.54 + This makes it possible to use jemalloc at the same time as the system
1.55 + allocator, or even to use multiple copies of jemalloc simultaneously.
1.56 +
1.57 + By default, the prefix is "", except on OS X, where it is "je_". On OS X,
1.58 + jemalloc overlays the default malloc zone, but makes no attempt to actually
1.59 + replace the "malloc", "calloc", etc. symbols.
1.60 +
1.61 +--without-export
1.62 + Don't export public APIs. This can be useful when building jemalloc as a
1.63 + static library, or to avoid exporting public APIs when using the zone
1.64 + allocator on OSX.
1.65 +
1.66 +--with-private-namespace=<prefix>
1.67 + Prefix all library-private APIs with <prefix>. For shared libraries,
1.68 + symbol visibility mechanisms prevent these symbols from being exported, but
1.69 + for static libraries, naming collisions are a real possibility. By
1.70 + default, the prefix is "" (empty string).
1.71 +
1.72 +--with-install-suffix=<suffix>
1.73 + Append <suffix> to the base name of all installed files, such that multiple
1.74 + versions of jemalloc can coexist in the same installation directory. For
1.75 + example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0.
1.76 +
1.77 +--enable-cc-silence
1.78 + Enable code that silences non-useful compiler warnings. This is helpful
1.79 + when trying to tell serious warnings from those due to compiler
1.80 + limitations, but it potentially incurs a performance penalty.
1.81 +
1.82 +--enable-debug
1.83 + Enable assertions and validation code. This incurs a substantial
1.84 + performance hit, but is very useful during application development.
1.85 +
1.86 +--disable-stats
1.87 + Disable statistics gathering functionality. See the "opt.stats_print"
1.88 + option documentation for usage details.
1.89 +
1.90 +--enable-prof
1.91 + Enable heap profiling and leak detection functionality. See the "opt.prof"
1.92 + option documentation for usage details. When enabled, there are several
1.93 + approaches to backtracing, and the configure script chooses the first one
1.94 + in the following list that appears to function correctly:
1.95 +
1.96 + + libunwind (requires --enable-prof-libunwind)
1.97 + + libgcc (unless --disable-prof-libgcc)
1.98 + + gcc intrinsics (unless --disable-prof-gcc)
1.99 +
1.100 +--enable-prof-libunwind
1.101 + Use the libunwind library (http://www.nongnu.org/libunwind/) for stack
1.102 + backtracing.
1.103 +
1.104 +--disable-prof-libgcc
1.105 + Disable the use of libgcc's backtracing functionality.
1.106 +
1.107 +--disable-prof-gcc
1.108 + Disable the use of gcc intrinsics for backtracing.
1.109 +
1.110 +--with-static-libunwind=<libunwind.a>
1.111 + Statically link against the specified libunwind.a rather than dynamically
1.112 + linking with -lunwind.
1.113 +
1.114 +--disable-tcache
1.115 + Disable thread-specific caches for small objects. Objects are cached and
1.116 + released in bulk, thus reducing the total number of mutex operations. See
1.117 + the "opt.tcache" option for usage details.
1.118 +
1.119 +--enable-mremap
1.120 + Enable huge realloc() via mremap(2). mremap() is disabled by default
1.121 + because the flavor used is specific to Linux, which has a quirk in its
1.122 + virtual memory allocation algorithm that causes semi-permanent VM map holes
1.123 + under normal jemalloc operation.
1.124 +
1.125 +--disable-munmap
1.126 + Disable virtual memory deallocation via munmap(2); instead keep track of
1.127 + the virtual memory for later use. munmap() is disabled by default (i.e.
1.128 + --disable-munmap is implied) on Linux, which has a quirk in its virtual
1.129 + memory allocation algorithm that causes semi-permanent VM map holes under
1.130 + normal jemalloc operation.
1.131 +
1.132 +--enable-dss
1.133 + Enable support for page allocation/deallocation via sbrk(2), in addition to
1.134 + mmap(2).
1.135 +
1.136 +--disable-fill
1.137 + Disable support for junk/zero filling of memory, quarantine, and redzones.
1.138 + See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option
1.139 + documentation for usage details.
1.140 +
1.141 +--disable-valgrind
1.142 + Disable support for Valgrind.
1.143 +
1.144 +--disable-experimental
1.145 + Disable support for the experimental API (*allocm()).
1.146 +
1.147 +--enable-utrace
1.148 + Enable utrace(2)-based allocation tracing. This feature is not broadly
1.149 + portable (FreeBSD has it, but Linux and OS X do not).
1.150 +
1.151 +--enable-xmalloc
1.152 + Enable support for optional immediate termination due to out-of-memory
1.153 + errors, as is commonly implemented by "xmalloc" wrapper function for malloc.
1.154 + See the "opt.xmalloc" option documentation for usage details.
1.155 +
1.156 +--enable-lazy-lock
1.157 + Enable code that wraps pthread_create() to detect when an application
1.158 + switches from single-threaded to multi-threaded mode, so that it can avoid
1.159 + mutex locking/unlocking operations while in single-threaded mode. In
1.160 + practice, this feature usually has little impact on performance unless
1.161 + thread-specific caching is disabled.
1.162 +
1.163 +--disable-tls
1.164 + Disable thread-local storage (TLS), which allows for fast access to
1.165 + thread-local variables via the __thread keyword. If TLS is available,
1.166 + jemalloc uses it for several purposes.
1.167 +
1.168 +--with-xslroot=<path>
1.169 + Specify where to find DocBook XSL stylesheets when building the
1.170 + documentation.
1.171 +
1.172 +The following environment variables (not a definitive list) impact configure's
1.173 +behavior:
1.174 +
1.175 +CFLAGS="?"
1.176 + Pass these flags to the compiler. You probably shouldn't define this unless
1.177 + you know what you are doing. (Use EXTRA_CFLAGS instead.)
1.178 +
1.179 +EXTRA_CFLAGS="?"
1.180 + Append these flags to CFLAGS. This makes it possible to add flags such as
1.181 + -Werror, while allowing the configure script to determine what other flags
1.182 + are appropriate for the specified configuration.
1.183 +
1.184 + The configure script specifically checks whether an optimization flag (-O*)
1.185 + is specified in EXTRA_CFLAGS, and refrains from specifying an optimization
1.186 + level if it finds that one has already been specified.
1.187 +
1.188 +CPPFLAGS="?"
1.189 + Pass these flags to the C preprocessor. Note that CFLAGS is not passed to
1.190 + 'cpp' when 'configure' is looking for include files, so you must use
1.191 + CPPFLAGS instead if you need to help 'configure' find header files.
1.192 +
1.193 +LD_LIBRARY_PATH="?"
1.194 + 'ld' uses this colon-separated list to find libraries.
1.195 +
1.196 +LDFLAGS="?"
1.197 + Pass these flags when linking.
1.198 +
1.199 +PATH="?"
1.200 + 'configure' uses this to find programs.
1.201 +
1.202 +=== Advanced compilation =======================================================
1.203 +
1.204 +To build only parts of jemalloc, use the following targets:
1.205 +
1.206 + build_lib_shared
1.207 + build_lib_static
1.208 + build_lib
1.209 + build_doc_html
1.210 + build_doc_man
1.211 + build_doc
1.212 +
1.213 +To install only parts of jemalloc, use the following targets:
1.214 +
1.215 + install_bin
1.216 + install_include
1.217 + install_lib_shared
1.218 + install_lib_static
1.219 + install_lib
1.220 + install_doc_html
1.221 + install_doc_man
1.222 + install_doc
1.223 +
1.224 +To clean up build results to varying degrees, use the following make targets:
1.225 +
1.226 + clean
1.227 + distclean
1.228 + relclean
1.229 +
1.230 +=== Advanced installation ======================================================
1.231 +
1.232 +Optionally, define make variables when invoking make, including (not
1.233 +exclusively):
1.234 +
1.235 +INCLUDEDIR="?"
1.236 + Use this as the installation prefix for header files.
1.237 +
1.238 +LIBDIR="?"
1.239 + Use this as the installation prefix for libraries.
1.240 +
1.241 +MANDIR="?"
1.242 + Use this as the installation prefix for man pages.
1.243 +
1.244 +DESTDIR="?"
1.245 + Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful
1.246 + when installing to a different path than was specified via --prefix.
1.247 +
1.248 +CC="?"
1.249 + Use this to invoke the C compiler.
1.250 +
1.251 +CFLAGS="?"
1.252 + Pass these flags to the compiler.
1.253 +
1.254 +CPPFLAGS="?"
1.255 + Pass these flags to the C preprocessor.
1.256 +
1.257 +LDFLAGS="?"
1.258 + Pass these flags when linking.
1.259 +
1.260 +PATH="?"
1.261 + Use this to search for programs used during configuration and building.
1.262 +
1.263 +=== Development ================================================================
1.264 +
1.265 +If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
1.266 +script rather than 'configure'. This re-generates 'configure', enables
1.267 +configuration dependency rules, and enables re-generation of automatically
1.268 +generated source files.
1.269 +
1.270 +The build system supports using an object directory separate from the source
1.271 +tree. For example, you can create an 'obj' directory, and from within that
1.272 +directory, issue configuration and build commands:
1.273 +
1.274 + autoconf
1.275 + mkdir obj
1.276 + cd obj
1.277 + ../configure --enable-autogen
1.278 + make
1.279 +
1.280 +=== Documentation ==============================================================
1.281 +
1.282 +The manual page is generated in both html and roff formats. Any web browser
1.283 +can be used to view the html manual. The roff manual page can be formatted
1.284 +prior to installation via the following command:
1.285 +
1.286 + nroff -man -t doc/jemalloc.3
