]>
Commit | Line | Data |
---|---|---|
4934f93d | 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-jemalloc-prefix=<prefix> | |
30 | Prefix all public APIs with <prefix>. For example, if <prefix> is | |
31 | "prefix_", API changes like the following occur: | |
32 | ||
33 | malloc() --> prefix_malloc() | |
34 | malloc_conf --> prefix_malloc_conf | |
35 | /etc/malloc.conf --> /etc/prefix_malloc.conf | |
36 | MALLOC_CONF --> PREFIX_MALLOC_CONF | |
37 | ||
38 | This makes it possible to use jemalloc at the same time as the system | |
39 | allocator, or even to use multiple copies of jemalloc simultaneously. | |
40 | ||
41 | By default, the prefix is "", except on OS X, where it is "je_". On OS X, | |
42 | jemalloc overlays the default malloc zone, but makes no attempt to actually | |
43 | replace the "malloc", "calloc", etc. symbols. | |
44 | ||
45 | --with-private-namespace=<prefix> | |
46 | Prefix all library-private APIs with <prefix>. For shared libraries, | |
47 | symbol visibility mechanisms prevent these symbols from being exported, but | |
48 | for static libraries, naming collisions are a real possibility. By | |
49 | default, the prefix is "" (empty string). | |
50 | ||
51 | --with-install-suffix=<suffix> | |
52 | Append <suffix> to the base name of all installed files, such that multiple | |
53 | versions of jemalloc can coexist in the same installation directory. For | |
54 | example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0. | |
55 | ||
56 | --enable-cc-silence | |
57 | Enable code that silences non-useful compiler warnings. This is helpful | |
58 | when trying to tell serious warnings from those due to compiler | |
59 | limitations, but it potentially incurs a performance penalty. | |
60 | ||
61 | --enable-debug | |
62 | Enable assertions and validation code. This incurs a substantial | |
63 | performance hit, but is very useful during application development. | |
64 | ||
65 | --enable-stats | |
66 | Enable statistics gathering functionality. See the "opt.stats_print" | |
67 | option documentation for usage details. | |
68 | ||
69 | --enable-prof | |
70 | Enable heap profiling and leak detection functionality. See the "opt.prof" | |
71 | option documentation for usage details. When enabled, there are several | |
72 | approaches to backtracing, and the configure script chooses the first one | |
73 | in the following list that appears to function correctly: | |
74 | ||
75 | + libunwind (requires --enable-prof-libunwind) | |
76 | + libgcc (unless --disable-prof-libgcc) | |
77 | + gcc intrinsics (unless --disable-prof-gcc) | |
78 | ||
79 | --enable-prof-libunwind | |
80 | Use the libunwind library (http://www.nongnu.org/libunwind/) for stack | |
81 | backtracing. | |
82 | ||
83 | --disable-prof-libgcc | |
84 | Disable the use of libgcc's backtracing functionality. | |
85 | ||
86 | --disable-prof-gcc | |
87 | Disable the use of gcc intrinsics for backtracing. | |
88 | ||
89 | --with-static-libunwind=<libunwind.a> | |
90 | Statically link against the specified libunwind.a rather than dynamically | |
91 | linking with -lunwind. | |
92 | ||
93 | --disable-tiny | |
94 | Disable tiny (sub-quantum-sized) object support. Technically it is not | |
95 | legal for a malloc implementation to allocate objects with less than | |
96 | quantum alignment (8 or 16 bytes, depending on architecture), but in | |
97 | practice it never causes any problems if, for example, 4-byte allocations | |
98 | are 4-byte-aligned. | |
99 | ||
100 | --disable-tcache | |
101 | Disable thread-specific caches for small objects. Objects are cached and | |
102 | released in bulk, thus reducing the total number of mutex operations. See | |
103 | the "opt.tcache" option for usage details. | |
104 | ||
105 | --enable-swap | |
106 | Enable mmap()ed swap file support. When this feature is built in, it is | |
107 | possible to specify one or more files that act as backing store. This | |
108 | effectively allows for per application swap files. | |
109 | ||
110 | --enable-dss | |
111 | Enable support for page allocation/deallocation via sbrk(2), in addition to | |
112 | mmap(2). | |
113 | ||
114 | --enable-fill | |
115 | Enable support for junk/zero filling of memory. See the "opt.junk"/ | |
116 | "opt.zero" option documentation for usage details. | |
117 | ||
118 | --enable-xmalloc | |
119 | Enable support for optional immediate termination due to out-of-memory | |
120 | errors, as is commonly implemented by "xmalloc" wrapper function for malloc. | |
121 | See the "opt.xmalloc" option documentation for usage details. | |
122 | ||
123 | --enable-sysv | |
124 | Enable support for System V semantics, wherein malloc(0) returns NULL | |
125 | rather than a minimal allocation. See the "opt.sysv" option documentation | |
126 | for usage details. | |
127 | ||
128 | --enable-dynamic-page-shift | |
129 | Under most conditions, the system page size never changes (usually 4KiB or | |
130 | 8KiB, depending on architecture and configuration), and unless this option | |
131 | is enabled, jemalloc assumes that page size can safely be determined during | |
132 | configuration and hard-coded. Enabling dynamic page size determination has | |
133 | a measurable impact on performance, since the compiler is forced to load | |
134 | the page size from memory rather than embedding immediate values. | |
135 | ||
136 | --disable-lazy-lock | |
137 | Disable code that wraps pthread_create() to detect when an application | |
138 | switches from single-threaded to multi-threaded mode, so that it can avoid | |
139 | mutex locking/unlocking operations while in single-threaded mode. In | |
140 | practice, this feature usually has little impact on performance unless | |
141 | thread-specific caching is disabled. | |
142 | ||
143 | --disable-tls | |
144 | Disable thread-local storage (TLS), which allows for fast access to | |
145 | thread-local variables via the __thread keyword. If TLS is available, | |
146 | jemalloc uses it for several purposes. | |
147 | ||
148 | --with-xslroot=<path> | |
149 | Specify where to find DocBook XSL stylesheets when building the | |
150 | documentation. | |
151 | ||
152 | The following environment variables (not a definitive list) impact configure's | |
153 | behavior: | |
154 | ||
155 | CFLAGS="?" | |
156 | Pass these flags to the compiler. You probably shouldn't define this unless | |
157 | you know what you are doing. (Use EXTRA_CFLAGS instead.) | |
158 | ||
159 | EXTRA_CFLAGS="?" | |
160 | Append these flags to CFLAGS. This makes it possible to add flags such as | |
161 | -Werror, while allowing the configure script to determine what other flags | |
162 | are appropriate for the specified configuration. | |
163 | ||
164 | The configure script specifically checks whether an optimization flag (-O*) | |
165 | is specified in EXTRA_CFLAGS, and refrains from specifying an optimization | |
166 | level if it finds that one has already been specified. | |
167 | ||
168 | CPPFLAGS="?" | |
169 | Pass these flags to the C preprocessor. Note that CFLAGS is not passed to | |
170 | 'cpp' when 'configure' is looking for include files, so you must use | |
171 | CPPFLAGS instead if you need to help 'configure' find header files. | |
172 | ||
173 | LD_LIBRARY_PATH="?" | |
174 | 'ld' uses this colon-separated list to find libraries. | |
175 | ||
176 | LDFLAGS="?" | |
177 | Pass these flags when linking. | |
178 | ||
179 | PATH="?" | |
180 | 'configure' uses this to find programs. | |
181 | ||
182 | === Advanced compilation ======================================================= | |
183 | ||
184 | To install only parts of jemalloc, use the following targets: | |
185 | ||
186 | install_bin | |
187 | install_include | |
188 | install_lib | |
189 | install_doc | |
190 | ||
191 | To clean up build results to varying degrees, use the following make targets: | |
192 | ||
193 | clean | |
194 | distclean | |
195 | relclean | |
196 | ||
197 | === Advanced installation ====================================================== | |
198 | ||
199 | Optionally, define make variables when invoking make, including (not | |
200 | exclusively): | |
201 | ||
202 | INCLUDEDIR="?" | |
203 | Use this as the installation prefix for header files. | |
204 | ||
205 | LIBDIR="?" | |
206 | Use this as the installation prefix for libraries. | |
207 | ||
208 | MANDIR="?" | |
209 | Use this as the installation prefix for man pages. | |
210 | ||
211 | DESTDIR="?" | |
212 | Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR. This is useful | |
213 | when installing to a different path than was specified via --prefix. | |
214 | ||
215 | CC="?" | |
216 | Use this to invoke the C compiler. | |
217 | ||
218 | CFLAGS="?" | |
219 | Pass these flags to the compiler. | |
220 | ||
221 | CPPFLAGS="?" | |
222 | Pass these flags to the C preprocessor. | |
223 | ||
224 | LDFLAGS="?" | |
225 | Pass these flags when linking. | |
226 | ||
227 | PATH="?" | |
228 | Use this to search for programs used during configuration and building. | |
229 | ||
230 | === Development ================================================================ | |
231 | ||
232 | If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh' | |
233 | script rather than 'configure'. This re-generates 'configure', enables | |
234 | configuration dependency rules, and enables re-generation of automatically | |
235 | generated source files. | |
236 | ||
237 | The build system supports using an object directory separate from the source | |
238 | tree. For example, you can create an 'obj' directory, and from within that | |
239 | directory, issue configuration and build commands: | |
240 | ||
241 | autoconf | |
242 | mkdir obj | |
243 | cd obj | |
244 | ../configure --enable-autogen | |
245 | make | |
246 | ||
247 | === Documentation ============================================================== | |
248 | ||
249 | The manual page is generated in both html and roff formats. Any web browser | |
250 | can be used to view the html manual. The roff manual page can be formatted | |
251 | prior to installation via any of the following commands: | |
252 | ||
253 | nroff -man -t doc/jemalloc.3 | |
254 | ||
255 | groff -man -t -Tps doc/jemalloc.3 | ps2pdf - doc/jemalloc.3.pdf | |
256 | ||
257 | (cd doc; groff -man -man-ext -t -Thtml jemalloc.3 > jemalloc.3.html) |