• file
• revisions
• annotate
• diff
• comparison
• raw

memory/jemalloc/src/INSTALL@6474c204b198 (annotated)

memory/jemalloc/src/INSTALL

Wed, 31 Dec 2014 06:09:35 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Wed, 31 Dec 2014 06:09:35 +0100

changeset 0

6474c204b198

permissions

-rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

michael@0	1	Building and installing jemalloc can be as simple as typing the following while
michael@0	2	in the root directory of the source tree:
michael@0	3
michael@0	4	./configure
michael@0	5	make
michael@0	6	make install
michael@0	7
michael@0	8	=== Advanced configuration =====================================================
michael@0	9
michael@0	10	The 'configure' script supports numerous options that allow control of which
michael@0	11	functionality is enabled, where jemalloc is installed, etc. Optionally, pass
michael@0	12	any of the following arguments (not a definitive list) to 'configure':
michael@0	13
michael@0	14	--help
michael@0	15	Print a definitive list of options.
michael@0	16
michael@0	17	--prefix=<install-root-dir>
michael@0	18	Set the base directory in which to install. For example:
michael@0	19
michael@0	20	./configure --prefix=/usr/local
michael@0	21
michael@0	22	will cause files to be installed into /usr/local/include, /usr/local/lib,
michael@0	23	and /usr/local/man.
michael@0	24
michael@0	25	--with-rpath=<colon-separated-rpath>
michael@0	26	Embed one or more library paths, so that libjemalloc can find the libraries
michael@0	27	it is linked to. This works only on ELF-based systems.
michael@0	28
michael@0	29	--with-mangling=<map>
michael@0	30	Mangle public symbols specified in <map> which is a comma-separated list of
michael@0	31	name:mangled pairs.
michael@0	32
michael@0	33	For example, to use ld's --wrap option as an alternative method for
michael@0	34	overriding libc's malloc implementation, specify something like:
michael@0	35
michael@0	36	--with-mangling=malloc:__wrap_malloc,free:__wrap_free[...]
michael@0	37
michael@0	38	Note that mangling happens prior to application of the prefix specified by
michael@0	39	--with-jemalloc-prefix, and mangled symbols are then ignored when applying
michael@0	40	the prefix.
michael@0	41
michael@0	42	--with-jemalloc-prefix=<prefix>
michael@0	43	Prefix all public APIs with <prefix>. For example, if <prefix> is
michael@0	44	"prefix_", API changes like the following occur:
michael@0	45
michael@0	46	malloc() --> prefix_malloc()
michael@0	47	malloc_conf --> prefix_malloc_conf
michael@0	48	/etc/malloc.conf --> /etc/prefix_malloc.conf
michael@0	49	MALLOC_CONF --> PREFIX_MALLOC_CONF
michael@0	50
michael@0	51	This makes it possible to use jemalloc at the same time as the system
michael@0	52	allocator, or even to use multiple copies of jemalloc simultaneously.
michael@0	53
michael@0	54	By default, the prefix is "", except on OS X, where it is "je_". On OS X,
michael@0	55	jemalloc overlays the default malloc zone, but makes no attempt to actually
michael@0	56	replace the "malloc", "calloc", etc. symbols.
michael@0	57
michael@0	58	--without-export
michael@0	59	Don't export public APIs. This can be useful when building jemalloc as a
michael@0	60	static library, or to avoid exporting public APIs when using the zone
michael@0	61	allocator on OSX.
michael@0	62
michael@0	63	--with-private-namespace=<prefix>
michael@0	64	Prefix all library-private APIs with <prefix>. For shared libraries,
michael@0	65	symbol visibility mechanisms prevent these symbols from being exported, but
michael@0	66	for static libraries, naming collisions are a real possibility. By
michael@0	67	default, the prefix is "" (empty string).
michael@0	68
michael@0	69	--with-install-suffix=<suffix>
michael@0	70	Append <suffix> to the base name of all installed files, such that multiple
michael@0	71	versions of jemalloc can coexist in the same installation directory. For
michael@0	72	example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0.
michael@0	73
michael@0	74	--enable-cc-silence
michael@0	75	Enable code that silences non-useful compiler warnings. This is helpful
michael@0	76	when trying to tell serious warnings from those due to compiler
michael@0	77	limitations, but it potentially incurs a performance penalty.
michael@0	78
michael@0	79	--enable-debug
michael@0	80	Enable assertions and validation code. This incurs a substantial
michael@0	81	performance hit, but is very useful during application development.
michael@0	82
michael@0	83	--disable-stats
michael@0	84	Disable statistics gathering functionality. See the "opt.stats_print"
michael@0	85	option documentation for usage details.
michael@0	86
michael@0	87	--enable-prof
michael@0	88	Enable heap profiling and leak detection functionality. See the "opt.prof"
michael@0	89	option documentation for usage details. When enabled, there are several
michael@0	90	approaches to backtracing, and the configure script chooses the first one
michael@0	91	in the following list that appears to function correctly:
michael@0	92
michael@0	93	+ libunwind (requires --enable-prof-libunwind)
michael@0	94	+ libgcc (unless --disable-prof-libgcc)
michael@0	95	+ gcc intrinsics (unless --disable-prof-gcc)
michael@0	96
michael@0	97	--enable-prof-libunwind
michael@0	98	Use the libunwind library (http://www.nongnu.org/libunwind/) for stack
michael@0	99	backtracing.
michael@0	100
michael@0	101	--disable-prof-libgcc
michael@0	102	Disable the use of libgcc's backtracing functionality.
michael@0	103
michael@0	104	--disable-prof-gcc
michael@0	105	Disable the use of gcc intrinsics for backtracing.
michael@0	106
michael@0	107	--with-static-libunwind=<libunwind.a>
michael@0	108	Statically link against the specified libunwind.a rather than dynamically
michael@0	109	linking with -lunwind.
michael@0	110
michael@0	111	--disable-tcache
michael@0	112	Disable thread-specific caches for small objects. Objects are cached and
michael@0	113	released in bulk, thus reducing the total number of mutex operations. See
michael@0	114	the "opt.tcache" option for usage details.
michael@0	115
michael@0	116	--enable-mremap
michael@0	117	Enable huge realloc() via mremap(2). mremap() is disabled by default
michael@0	118	because the flavor used is specific to Linux, which has a quirk in its
michael@0	119	virtual memory allocation algorithm that causes semi-permanent VM map holes
michael@0	120	under normal jemalloc operation.
michael@0	121
michael@0	122	--disable-munmap
michael@0	123	Disable virtual memory deallocation via munmap(2); instead keep track of
michael@0	124	the virtual memory for later use. munmap() is disabled by default (i.e.
michael@0	125	--disable-munmap is implied) on Linux, which has a quirk in its virtual
michael@0	126	memory allocation algorithm that causes semi-permanent VM map holes under
michael@0	127	normal jemalloc operation.
michael@0	128
michael@0	129	--enable-dss
michael@0	130	Enable support for page allocation/deallocation via sbrk(2), in addition to
michael@0	131	mmap(2).
michael@0	132
michael@0	133	--disable-fill
michael@0	134	Disable support for junk/zero filling of memory, quarantine, and redzones.
michael@0	135	See the "opt.junk", "opt.zero", "opt.quarantine", and "opt.redzone" option
michael@0	136	documentation for usage details.
michael@0	137
michael@0	138	--disable-valgrind
michael@0	139	Disable support for Valgrind.
michael@0	140
michael@0	141	--disable-experimental
michael@0	142	Disable support for the experimental API (*allocm()).
michael@0	143
michael@0	144	--enable-utrace
michael@0	145	Enable utrace(2)-based allocation tracing. This feature is not broadly
michael@0	146	portable (FreeBSD has it, but Linux and OS X do not).
michael@0	147
michael@0	148	--enable-xmalloc
michael@0	149	Enable support for optional immediate termination due to out-of-memory
michael@0	150	errors, as is commonly implemented by "xmalloc" wrapper function for malloc.
michael@0	151	See the "opt.xmalloc" option documentation for usage details.
michael@0	152
michael@0	153	--enable-lazy-lock
michael@0	154	Enable code that wraps pthread_create() to detect when an application
michael@0	155	switches from single-threaded to multi-threaded mode, so that it can avoid
michael@0	156	mutex locking/unlocking operations while in single-threaded mode. In
michael@0	157	practice, this feature usually has little impact on performance unless
michael@0	158	thread-specific caching is disabled.
michael@0	159
michael@0	160	--disable-tls
michael@0	161	Disable thread-local storage (TLS), which allows for fast access to
michael@0	162	thread-local variables via the __thread keyword. If TLS is available,
michael@0	163	jemalloc uses it for several purposes.
michael@0	164
michael@0	165	--with-xslroot=<path>
michael@0	166	Specify where to find DocBook XSL stylesheets when building the
michael@0	167	documentation.
michael@0	168
michael@0	169	The following environment variables (not a definitive list) impact configure's
michael@0	170	behavior:
michael@0	171
michael@0	172	CFLAGS="?"
michael@0	173	Pass these flags to the compiler. You probably shouldn't define this unless
michael@0	174	you know what you are doing. (Use EXTRA_CFLAGS instead.)
michael@0	175
michael@0	176	EXTRA_CFLAGS="?"
michael@0	177	Append these flags to CFLAGS. This makes it possible to add flags such as
michael@0	178	-Werror, while allowing the configure script to determine what other flags
michael@0	179	are appropriate for the specified configuration.
michael@0	180
michael@0	181	The configure script specifically checks whether an optimization flag (-O*)
michael@0	182	is specified in EXTRA_CFLAGS, and refrains from specifying an optimization
michael@0	183	level if it finds that one has already been specified.
michael@0	184
michael@0	185	CPPFLAGS="?"
michael@0	186	Pass these flags to the C preprocessor. Note that CFLAGS is not passed to
michael@0	187	'cpp' when 'configure' is looking for include files, so you must use
michael@0	188	CPPFLAGS instead if you need to help 'configure' find header files.
michael@0	189
michael@0	190	LD_LIBRARY_PATH="?"
michael@0	191	'ld' uses this colon-separated list to find libraries.
michael@0	192
michael@0	193	LDFLAGS="?"
michael@0	194	Pass these flags when linking.
michael@0	195
michael@0	196	PATH="?"
michael@0	197	'configure' uses this to find programs.
michael@0	198
michael@0	199	=== Advanced compilation =======================================================
michael@0	200
michael@0	201	To build only parts of jemalloc, use the following targets:
michael@0	202
michael@0	203	build_lib_shared
michael@0	204	build_lib_static
michael@0	205	build_lib
michael@0	206	build_doc_html
michael@0	207	build_doc_man
michael@0	208	build_doc
michael@0	209
michael@0	210	To install only parts of jemalloc, use the following targets:
michael@0	211
michael@0	212	install_bin
michael@0	213	install_include
michael@0	214	install_lib_shared
michael@0	215	install_lib_static
michael@0	216	install_lib
michael@0	217	install_doc_html
michael@0	218	install_doc_man
michael@0	219	install_doc
michael@0	220
michael@0	221	To clean up build results to varying degrees, use the following make targets:
michael@0	222
michael@0	223	clean
michael@0	224	distclean
michael@0	225	relclean
michael@0	226
michael@0	227	=== Advanced installation ======================================================
michael@0	228
michael@0	229	Optionally, define make variables when invoking make, including (not
michael@0	230	exclusively):
michael@0	231
michael@0	232	INCLUDEDIR="?"
michael@0	233	Use this as the installation prefix for header files.
michael@0	234
michael@0	235	LIBDIR="?"
michael@0	236	Use this as the installation prefix for libraries.
michael@0	237
michael@0	238	MANDIR="?"
michael@0	239	Use this as the installation prefix for man pages.
michael@0	240
michael@0	241	DESTDIR="?"
michael@0	242	Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful
michael@0	243	when installing to a different path than was specified via --prefix.
michael@0	244
michael@0	245	CC="?"
michael@0	246	Use this to invoke the C compiler.
michael@0	247
michael@0	248	CFLAGS="?"
michael@0	249	Pass these flags to the compiler.
michael@0	250
michael@0	251	CPPFLAGS="?"
michael@0	252	Pass these flags to the C preprocessor.
michael@0	253
michael@0	254	LDFLAGS="?"
michael@0	255	Pass these flags when linking.
michael@0	256
michael@0	257	PATH="?"
michael@0	258	Use this to search for programs used during configuration and building.
michael@0	259
michael@0	260	=== Development ================================================================
michael@0	261
michael@0	262	If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
michael@0	263	script rather than 'configure'. This re-generates 'configure', enables
michael@0	264	configuration dependency rules, and enables re-generation of automatically
michael@0	265	generated source files.
michael@0	266
michael@0	267	The build system supports using an object directory separate from the source
michael@0	268	tree. For example, you can create an 'obj' directory, and from within that
michael@0	269	directory, issue configuration and build commands:
michael@0	270
michael@0	271	autoconf
michael@0	272	mkdir obj
michael@0	273	cd obj
michael@0	274	../configure --enable-autogen
michael@0	275	make
michael@0	276
michael@0	277	=== Documentation ==============================================================
michael@0	278
michael@0	279	The manual page is generated in both html and roff formats. Any web browser
michael@0	280	can be used to view the html manual. The roff manual page can be formatted
michael@0	281	prior to installation via the following command:
michael@0	282
michael@0	283	nroff -man -t doc/jemalloc.3