]>
Commit | Line | Data |
---|---|---|
1 | Building and installing jemalloc can be as simple as typing the following while | |
2 | in the root directory of the source tree: | |
3 | ||
4 | ./configure | |
5 | make | |
6 | make install | |
7 | ||
8 | === Advanced configuration ===================================================== | |
9 | ||
10 | The 'configure' script supports numerous options that allow control of which | |
11 | functionality is enabled, where jemalloc is installed, etc. Optionally, pass | |
12 | any 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 | ||
164 | The following environment variables (not a definitive list) impact configure's | |
165 | behavior: | |
166 | ||
167 | CFLAGS="?" | |
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 | ||
171 | EXTRA_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 | ||
180 | CPPFLAGS="?" | |
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 | ||
185 | LD_LIBRARY_PATH="?" | |
186 | 'ld' uses this colon-separated list to find libraries. | |
187 | ||
188 | LDFLAGS="?" | |
189 | Pass these flags when linking. | |
190 | ||
191 | PATH="?" | |
192 | 'configure' uses this to find programs. | |
193 | ||
194 | === Advanced compilation ======================================================= | |
195 | ||
196 | To 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 | ||
205 | To 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 | ||
216 | To clean up build results to varying degrees, use the following make targets: | |
217 | ||
218 | clean | |
219 | distclean | |
220 | relclean | |
221 | ||
222 | === Advanced installation ====================================================== | |
223 | ||
224 | Optionally, define make variables when invoking make, including (not | |
225 | exclusively): | |
226 | ||
227 | INCLUDEDIR="?" | |
228 | Use this as the installation prefix for header files. | |
229 | ||
230 | LIBDIR="?" | |
231 | Use this as the installation prefix for libraries. | |
232 | ||
233 | MANDIR="?" | |
234 | Use this as the installation prefix for man pages. | |
235 | ||
236 | DESTDIR="?" | |
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 | ||
240 | CC="?" | |
241 | Use this to invoke the C compiler. | |
242 | ||
243 | CFLAGS="?" | |
244 | Pass these flags to the compiler. | |
245 | ||
246 | CPPFLAGS="?" | |
247 | Pass these flags to the C preprocessor. | |
248 | ||
249 | LDFLAGS="?" | |
250 | Pass these flags when linking. | |
251 | ||
252 | PATH="?" | |
253 | Use this to search for programs used during configuration and building. | |
254 | ||
255 | === Development ================================================================ | |
256 | ||
257 | If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' | |
258 | script rather than 'configure'. This re-generates 'configure', enables | |
259 | configuration dependency rules, and enables re-generation of automatically | |
260 | generated source files. | |
261 | ||
262 | The build system supports using an object directory separate from the source | |
263 | tree. For example, you can create an 'obj' directory, and from within that | |
264 | directory, issue configuration and build commands: | |
265 | ||
266 | autoconf | |
267 | mkdir obj | |
268 | cd obj | |
269 | ../configure --enable-autogen | |
270 | make | |
271 | ||
272 | === Documentation ============================================================== | |
273 | ||
274 | The manual page is generated in both html and roff formats. Any web browser | |
275 | can be used to view the html manual. The roff manual page can be formatted | |
276 | prior to installation via the following command: | |
277 | ||
278 | nroff -man -t doc/jemalloc.3 |