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