summaryrefslogtreecommitdiff
path: root/memory/jemalloc/src/INSTALL
diff options
context:
space:
mode:
authorwolfbeast <mcwerewolf@gmail.com>2018-04-27 19:16:45 +0200
committerwolfbeast <mcwerewolf@gmail.com>2018-04-27 19:16:45 +0200
commit43034a36e132ac4394e26cbfb4d855bd6f5114b3 (patch)
treeaee5502c6b17283b80ff2bf0706f97622df5d355 /memory/jemalloc/src/INSTALL
parent077c63084488ac38c1c44e8cdaa9c33086f0a649 (diff)
downloaduxp-43034a36e132ac4394e26cbfb4d855bd6f5114b3.tar.gz
Remove jemalloc 4 from our tree.
Diffstat (limited to 'memory/jemalloc/src/INSTALL')
-rw-r--r--memory/jemalloc/src/INSTALL414
1 files changed, 0 insertions, 414 deletions
diff --git a/memory/jemalloc/src/INSTALL b/memory/jemalloc/src/INSTALL
deleted file mode 100644
index 6878716535..0000000000
--- a/memory/jemalloc/src/INSTALL
+++ /dev/null
@@ -1,414 +0,0 @@
-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