summaryrefslogtreecommitdiffstats
path: root/memory/jemalloc/src/INSTALL
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /memory/jemalloc/src/INSTALL
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'memory/jemalloc/src/INSTALL')
-rw-r--r--memory/jemalloc/src/INSTALL414
1 files changed, 414 insertions, 0 deletions
diff --git a/memory/jemalloc/src/INSTALL b/memory/jemalloc/src/INSTALL
new file mode 100644
index 000000000..687871653
--- /dev/null
+++ b/memory/jemalloc/src/INSTALL
@@ -0,0 +1,414 @@
+Building and installing a packaged release of jemalloc can be as simple as
+typing the following while in the root directory of the source tree:
+
+ ./configure
+ make
+ make install
+
+If building from unpackaged developer sources, the simplest command sequence
+that might work is:
+
+ ./autogen.sh
+ make dist
+ make
+ make install
+
+Note that documentation is not built by the default target because doing so
+would create a dependency on xsltproc in packaged releases, hence the
+requirement to either run 'make dist' or avoid installing docs via the various
+install_* targets documented below.
+
+=== Advanced configuration =====================================================
+
+The 'configure' script supports numerous options that allow control of which
+functionality is enabled, where jemalloc is installed, etc. Optionally, pass
+any of the following arguments (not a definitive list) to 'configure':
+
+--help
+ Print a definitive list of options.
+
+--prefix=<install-root-dir>
+ Set the base directory in which to install. For example:
+
+ ./configure --prefix=/usr/local
+
+ will cause files to be installed into /usr/local/include, /usr/local/lib,
+ and /usr/local/man.
+
+--with-version=<major>.<minor>.<bugfix>-<nrev>-g<gid>
+ Use the specified version string rather than trying to generate one (if in
+ a git repository) or use existing the VERSION file (if present).
+
+--with-rpath=<colon-separated-rpath>
+ Embed one or more library paths, so that libjemalloc can find the libraries
+ it is linked to. This works only on ELF-based systems.
+
+--with-mangling=<map>
+ Mangle public symbols specified in <map> which is a comma-separated list of
+ name:mangled pairs.
+
+ For example, to use ld's --wrap option as an alternative method for
+ overriding libc's malloc implementation, specify something like:
+
+ --with-mangling=malloc:__wrap_malloc,free:__wrap_free[...]
+
+ Note that mangling happens prior to application of the prefix specified by
+ --with-jemalloc-prefix, and mangled symbols are then ignored when applying
+ the prefix.
+
+--with-jemalloc-prefix=<prefix>
+ Prefix all public APIs with <prefix>. For example, if <prefix> is
+ "prefix_", API changes like the following occur:
+
+ malloc() --> prefix_malloc()
+ malloc_conf --> prefix_malloc_conf
+ /etc/malloc.conf --> /etc/prefix_malloc.conf
+ MALLOC_CONF --> PREFIX_MALLOC_CONF
+
+ This makes it possible to use jemalloc at the same time as the system
+ allocator, or even to use multiple copies of jemalloc simultaneously.
+
+ By default, the prefix is "", except on OS X, where it is "je_". On OS X,
+ jemalloc overlays the default malloc zone, but makes no attempt to actually
+ replace the "malloc", "calloc", etc. symbols.
+
+--without-export
+ Don't export public APIs. This can be useful when building jemalloc as a
+ static library, or to avoid exporting public APIs when using the zone
+ allocator on OSX.
+
+--with-private-namespace=<prefix>
+ Prefix all library-private APIs with <prefix>je_. For shared libraries,
+ symbol visibility mechanisms prevent these symbols from being exported, but
+ for static libraries, naming collisions are a real possibility. By
+ default, <prefix> is empty, which results in a symbol prefix of je_ .
+
+--with-install-suffix=<suffix>
+ Append <suffix> to the base name of all installed files, such that multiple
+ versions of jemalloc can coexist in the same installation directory. For
+ example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0.
+
+--with-malloc-conf=<malloc_conf>
+ Embed <malloc_conf> as a run-time options string that is processed prior to
+ the malloc_conf global variable, the /etc/malloc.conf symlink, and the
+ MALLOC_CONF environment variable. For example, to change the default chunk
+ size to 256 KiB:
+
+ --with-malloc-conf=lg_chunk:18
+
+--disable-cc-silence
+ Disable code that silences non-useful compiler warnings. This is mainly
+ useful during development when auditing the set of warnings that are being
+ silenced.
+
+--enable-debug
+ Enable assertions and validation code. This incurs a substantial
+ performance hit, but is very useful during application development.
+ Implies --enable-ivsalloc.
+
+--enable-code-coverage
+ Enable code coverage support, for use during jemalloc test development.
+ Additional testing targets are available if this option is enabled:
+
+ coverage
+ coverage_unit
+ coverage_integration
+ coverage_stress
+
+ These targets do not clear code coverage results from previous runs, and
+ there are interactions between the various coverage targets, so it is
+ usually advisable to run 'make clean' between repeated code coverage runs.
+
+--disable-stats
+ Disable statistics gathering functionality. See the "opt.stats_print"
+ option documentation for usage details.
+
+--enable-ivsalloc
+ Enable validation code, which verifies that pointers reside within
+ jemalloc-owned chunks before dereferencing them. This incurs a minor
+ performance hit.
+
+--enable-prof
+ Enable heap profiling and leak detection functionality. See the "opt.prof"
+ option documentation for usage details. When enabled, there are several
+ approaches to backtracing, and the configure script chooses the first one
+ in the following list that appears to function correctly:
+
+ + libunwind (requires --enable-prof-libunwind)
+ + libgcc (unless --disable-prof-libgcc)
+ + gcc intrinsics (unless --disable-prof-gcc)
+
+--enable-prof-libunwind
+ Use the libunwind library (http://www.nongnu.org/libunwind/) for stack
+ backtracing.
+
+--disable-prof-libgcc
+ Disable the use of libgcc's backtracing functionality.
+
+--disable-prof-gcc
+ Disable the use of gcc intrinsics for backtracing.
+
+--with-static-libunwind=<libunwind.a>
+ Statically link against the specified libunwind.a rather than dynamically
+ linking with -lunwind.
+
+--disable-tcache
+ Disable thread-specific caches for small objects. Objects are cached and
+ released in bulk, thus reducing the total number of mutex operations. See
+ the "opt.tcache" option for usage details.
+
+--disable-munmap
+ Disable virtual memory deallocation via munmap(2); instead keep track of
+ the virtual memory for later use. munmap() is disabled by default (i.e.
+ --disable-munmap is implied) on Linux, which has a quirk in its virtual
+ memory allocation algorithm that causes semi-permanent VM map holes under
+ normal jemalloc operation.
+
+--disable-fill
+ Disable support for junk/zero filling of memory, quarantine, and redzones.
+ See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option
+ documentation for usage details.
+
+--disable-valgrind
+ Disable support for Valgrind.
+
+--disable-zone-allocator
+ Disable zone allocator for Darwin. This means jemalloc won't be hooked as
+ the default allocator on OSX/iOS.
+
+--enable-utrace
+ Enable utrace(2)-based allocation tracing. This feature is not broadly
+ portable (FreeBSD has it, but Linux and OS X do not).
+
+--enable-xmalloc
+ Enable support for optional immediate termination due to out-of-memory
+ errors, as is commonly implemented by "xmalloc" wrapper function for malloc.
+ See the "opt.xmalloc" option documentation for usage details.
+
+--enable-lazy-lock
+ Enable code that wraps pthread_create() to detect when an application
+ switches from single-threaded to multi-threaded mode, so that it can avoid
+ mutex locking/unlocking operations while in single-threaded mode. In
+ practice, this feature usually has little impact on performance unless
+ thread-specific caching is disabled.
+
+--disable-tls
+ Disable thread-local storage (TLS), which allows for fast access to
+ thread-local variables via the __thread keyword. If TLS is available,
+ jemalloc uses it for several purposes.
+
+--disable-cache-oblivious
+ Disable cache-oblivious large allocation alignment for large allocation
+ requests with no alignment constraints. If this feature is disabled, all
+ large allocations are page-aligned as an implementation artifact, which can
+ severely harm CPU cache utilization. However, the cache-oblivious layout
+ comes at the cost of one extra page per large allocation, which in the
+ most extreme case increases physical memory usage for the 16 KiB size class
+ to 20 KiB.
+
+--with-xslroot=<path>
+ Specify where to find DocBook XSL stylesheets when building the
+ documentation.
+
+--with-lg-page=<lg-page>
+ Specify the base 2 log of the system page size. This option is only useful
+ when cross compiling, since the configure script automatically determines
+ the host's page size by default.
+
+--with-lg-page-sizes=<lg-page-sizes>
+ Specify the comma-separated base 2 logs of the page sizes to support. This
+ option may be useful when cross-compiling in combination with
+ --with-lg-page, but its primary use case is for integration with FreeBSD's
+ libc, wherein jemalloc is embedded.
+
+--with-lg-size-class-group=<lg-size-class-group>
+ Specify the base 2 log of how many size classes to use for each doubling in
+ size. By default jemalloc uses <lg-size-class-group>=2, which results in
+ e.g. the following size classes:
+
+ [...], 64,
+ 80, 96, 112, 128,
+ 160, [...]
+
+ <lg-size-class-group>=3 results in e.g. the following size classes:
+
+ [...], 64,
+ 72, 80, 88, 96, 104, 112, 120, 128,
+ 144, [...]
+
+ The minimal <lg-size-class-group>=0 causes jemalloc to only provide size
+ classes that are powers of 2:
+
+ [...],
+ 64,
+ 128,
+ 256,
+ [...]
+
+ An implementation detail currently limits the total number of small size
+ classes to 255, and a compilation error will result if the
+ <lg-size-class-group> you specify cannot be supported. The limit is
+ roughly <lg-size-class-group>=4, depending on page size.
+
+--with-lg-quantum=<lg-quantum>
+ Specify the base 2 log of the minimum allocation alignment. jemalloc needs
+ to know the minimum alignment that meets the following C standard
+ requirement (quoted from the April 12, 2011 draft of the C11 standard):
+
+ The pointer returned if the allocation succeeds is suitably aligned so
+ that it may be assigned to a pointer to any type of object with a
+ fundamental alignment requirement and then used to access such an object
+ or an array of such objects in the space allocated [...]
+
+ This setting is architecture-specific, and although jemalloc includes known
+ safe values for the most commonly used modern architectures, there is a
+ wrinkle related to GNU libc (glibc) that may impact your choice of
+ <lg-quantum>. On most modern architectures, this mandates 16-byte alignment
+ (<lg-quantum>=4), but the glibc developers chose not to meet this
+ requirement for performance reasons. An old discussion can be found at
+ https://sourceware.org/bugzilla/show_bug.cgi?id=206 . Unlike glibc,
+ jemalloc does follow the C standard by default (caveat: jemalloc
+ technically cheats if --with-lg-tiny-min is smaller than
+ --with-lg-quantum), but the fact that Linux systems already work around
+ this allocator noncompliance means that it is generally safe in practice to
+ let jemalloc's minimum alignment follow glibc's lead. If you specify
+ --with-lg-quantum=3 during configuration, jemalloc will provide additional
+ size classes that are not 16-byte-aligned (24, 40, and 56, assuming
+ --with-lg-size-class-group=2).
+
+--with-lg-tiny-min=<lg-tiny-min>
+ Specify the base 2 log of the minimum tiny size class to support. Tiny
+ size classes are powers of 2 less than the quantum, and are only
+ incorporated if <lg-tiny-min> is less than <lg-quantum> (see
+ --with-lg-quantum). Tiny size classes technically violate the C standard
+ requirement for minimum alignment, and crashes could conceivably result if
+ the compiler were to generate instructions that made alignment assumptions,
+ both because illegal instruction traps could result, and because accesses
+ could straddle page boundaries and cause segmentation faults due to
+ accessing unmapped addresses.
+
+ The default of <lg-tiny-min>=3 works well in practice even on architectures
+ that technically require 16-byte alignment, probably for the same reason
+ --with-lg-quantum=3 works. Smaller tiny size classes can, and will, cause
+ crashes (see https://bugzilla.mozilla.org/show_bug.cgi?id=691003 for an
+ example).
+
+ This option is rarely useful, and is mainly provided as documentation of a
+ subtle implementation detail. If you do use this option, specify a
+ value in [3, ..., <lg-quantum>].
+
+The following environment variables (not a definitive list) impact configure's
+behavior:
+
+CFLAGS="?"
+ Pass these flags to the compiler. You probably shouldn't define this unless
+ you know what you are doing. (Use EXTRA_CFLAGS instead.)
+
+EXTRA_CFLAGS="?"
+ Append these flags to CFLAGS. This makes it possible to add flags such as
+ -Werror, while allowing the configure script to determine what other flags
+ are appropriate for the specified configuration.
+
+ The configure script specifically checks whether an optimization flag (-O*)
+ is specified in EXTRA_CFLAGS, and refrains from specifying an optimization
+ level if it finds that one has already been specified.
+
+CPPFLAGS="?"
+ Pass these flags to the C preprocessor. Note that CFLAGS is not passed to
+ 'cpp' when 'configure' is looking for include files, so you must use
+ CPPFLAGS instead if you need to help 'configure' find header files.
+
+LD_LIBRARY_PATH="?"
+ 'ld' uses this colon-separated list to find libraries.
+
+LDFLAGS="?"
+ Pass these flags when linking.
+
+PATH="?"
+ 'configure' uses this to find programs.
+
+=== Advanced compilation =======================================================
+
+To build only parts of jemalloc, use the following targets:
+
+ build_lib_shared
+ build_lib_static
+ build_lib
+ build_doc_html
+ build_doc_man
+ build_doc
+
+To install only parts of jemalloc, use the following targets:
+
+ install_bin
+ install_include
+ install_lib_shared
+ install_lib_static
+ install_lib
+ install_doc_html
+ install_doc_man
+ install_doc
+
+To clean up build results to varying degrees, use the following make targets:
+
+ clean
+ distclean
+ relclean
+
+=== Advanced installation ======================================================
+
+Optionally, define make variables when invoking make, including (not
+exclusively):
+
+INCLUDEDIR="?"
+ Use this as the installation prefix for header files.
+
+LIBDIR="?"
+ Use this as the installation prefix for libraries.
+
+MANDIR="?"
+ Use this as the installation prefix for man pages.
+
+DESTDIR="?"
+ Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful
+ when installing to a different path than was specified via --prefix.
+
+CC="?"
+ Use this to invoke the C compiler.
+
+CFLAGS="?"
+ Pass these flags to the compiler.
+
+CPPFLAGS="?"
+ Pass these flags to the C preprocessor.
+
+LDFLAGS="?"
+ Pass these flags when linking.
+
+PATH="?"
+ Use this to search for programs used during configuration and building.
+
+=== Development ================================================================
+
+If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
+script rather than 'configure'. This re-generates 'configure', enables
+configuration dependency rules, and enables re-generation of automatically
+generated source files.
+
+The build system supports using an object directory separate from the source
+tree. For example, you can create an 'obj' directory, and from within that
+directory, issue configuration and build commands:
+
+ autoconf
+ mkdir obj
+ cd obj
+ ../configure --enable-autogen
+ make
+
+=== Documentation ==============================================================
+
+The manual page is generated in both html and roff formats. Any web browser
+can be used to view the html manual. The roff manual page can be formatted
+prior to installation via the following command:
+
+ nroff -man -t doc/jemalloc.3