1 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
2 xml:id="manual.intro.setup.configure" xreflabel="Configuring">
3 <?dbhtml filename="configure.html"?>
5 <info><title>Configure</title>
22 When configuring libstdc++, you'll have to configure the entire
23 <emphasis>gccsrcdir</emphasis> directory. Consider using the
24 toplevel gcc configuration option
25 <literal>--enable-languages=c++</literal>, which saves time by only
26 building the C++ toolchain.
30 Here are all of the configure options specific to libstdc++. Keep
32 <!-- This SECnn should be the "Choosing Package Options" section. -->
33 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/autobook/autobook/autobook_14.html">they
34 all have opposite forms as well</link> (enable/disable and
35 with/without). The defaults are for the <emphasis>current
36 development sources</emphasis>, which may be different than those
37 for released versions.
39 <para>The canonical way to find out the configure options that are
40 available for a given set of libstdc++ sources is to go to the
41 source directory and then type: <command>./configure --help</command>.
45 <varlistentry><term><code>--enable-multilib</code>[default]</term>
46 <listitem><para>This is part of the generic multilib support for building cross
47 compilers. As such, targets like "powerpc-elf" will have
48 libstdc++ built many different ways: "-msoft-float"
49 and not, etc. A different libstdc++ will be built for each of
50 the different multilib versions. This option is on by default.
52 </listitem></varlistentry>
54 <varlistentry><term><code>--enable-sjlj-exceptions</code></term>
55 <listitem><para>Forces old, set-jump/long-jump exception handling model. If
56 at all possible, the new, frame unwinding exception handling routines
57 should be used instead, as they significantly reduce both
58 runtime memory usage and executable size. This option can
59 change the library ABI.
61 </listitem></varlistentry>
63 <varlistentry><term><code>--enable-version-specific-runtime-libs</code></term>
64 <listitem><para>Specify that run-time libraries should be installed in the
65 compiler-specific subdirectory (i.e.,
66 <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>)
67 instead of <code>${libdir}</code>. This option is useful if you
68 intend to use several versions of gcc in parallel. In addition,
69 libstdc++'s include files will be installed in
70 <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>,
71 unless you also specify
72 <literal>--with-gxx-include-dir=</literal><filename class="directory">dirname</filename> during configuration.
74 </listitem></varlistentry>
76 <varlistentry><term><code>--with-gxx-include-dir=<include-files dir></code></term>
77 <listitem><para>Adds support for named libstdc++ include directory. For instance,
78 the following puts all the libstdc++ headers into a directory
79 called "4.4-20090404" instead of the usual
83 --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/4.4-20090404</programlisting> </listitem></varlistentry>
85 <varlistentry><term><code>--enable-cstdio</code></term>
86 <listitem><para>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code>
89 </listitem></varlistentry>
91 <varlistentry><term><code>--enable-cstdio=OPTION</code></term>
92 <listitem><para>Select a target-specific I/O package. At the moment, the only
93 choice is to use 'stdio', a generic "C" abstraction.
94 The default is 'stdio'. This option can change the library ABI.
96 </listitem></varlistentry>
98 <varlistentry><term><code>--enable-clocale</code></term>
99 <listitem><para>This is an abbreviated form of <code>'--enable-clocale=generic'</code>
102 </listitem></varlistentry>
104 <varlistentry><term><code>--enable-clocale=OPTION</code></term>
105 <listitem><para>Select a target-specific underlying locale package. The
106 choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix
107 (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets,
108 'gnu' to specify a model based on functionality from the GNU C
109 library (langinfo/iconv/gettext) (from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sources.redhat.com/glibc/">glibc</link>, the GNU C
110 library), 'generic' to use a generic "C" abstraction which consists
111 of "C" locale info, 'newlib' to specify the Newlib C library model
112 which only differs from the 'generic' model in the handling of
113 ctype, or 'darwin' which omits the <type>wchar_t</type> specializations
114 needed by the 'generic' model.
117 <para>If not explicitly specified, the configure process tries
118 to guess the most suitable package from the choices above. The
119 default is 'generic'. On glibc-based systems of sufficient
120 vintage (2.3 and newer), 'gnu' is automatically selected. On newlib-based
121 systems (<code>'--with_newlib=yes'</code>) and OpenBSD, 'newlib' is
122 automatically selected. On Mac OS X 'darwin' is automatically selected.
123 This option can change the library ABI.
125 </listitem></varlistentry>
127 <varlistentry><term><code>--enable-libstdcxx-allocator</code></term>
128 <listitem><para>This is an abbreviated form of
129 <code>'--enable-libstdcxx-allocator=auto'</code> (described
132 </listitem></varlistentry>
134 <varlistentry><term><code>--enable-libstdcxx-allocator=OPTION </code></term>
135 <listitem><para>Select a target-specific underlying std::allocator. The
136 choices are 'new' to specify a wrapper for new, 'malloc' to
137 specify a wrapper for malloc, 'mt' for a fixed power of two allocator,
138 'pool' for the SGI pooled allocator or 'bitmap' for a bitmap allocator.
139 See this page for more information on allocator
140 <link linkend="allocator.ext">extensions</link>. This option
141 can change the library ABI.
143 </listitem></varlistentry>
145 <varlistentry><term><code>--enable-cheaders=OPTION</code></term>
146 <listitem><para>This allows the user to define the approach taken for C header
147 compatibility with C++. Options are c, c_std, and c_global.
148 These correspond to the source directory's include/c,
149 include/c_std, and include/c_global, and may also include
150 include/c_compatibility. The default is 'c_global'.
152 </listitem></varlistentry>
154 <varlistentry><term><code>--enable-threads</code></term>
155 <listitem><para>This is an abbreviated form of <code>'--enable-threads=yes'</code>
158 </listitem></varlistentry>
160 <varlistentry><term><code>--enable-threads=OPTION</code></term>
161 <listitem><para>Select a threading library. A full description is
163 general <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/configure.html">compiler
164 configuration instructions</link>. This option can change the
167 </listitem></varlistentry>
169 <varlistentry><term><code>--enable-libstdcxx-threads</code></term>
170 <listitem><para>Enable C++11 threads support. If not explicitly specified,
171 the configure process enables it if possible. It defaults to 'off'
172 on Solaris 9, where it would break symbol versioning. This
173 option can change the library ABI.
175 </listitem></varlistentry>
177 <varlistentry><term><code>--enable-libstdcxx-time</code></term>
178 <listitem><para>This is an abbreviated form of
179 <code>'--enable-libstdcxx-time=yes'</code>(described next).
181 </listitem></varlistentry>
183 <varlistentry><term><code>--enable-libstdcxx-time=OPTION</code></term>
184 <listitem><para>Enables link-type checks for the availability of the
185 clock_gettime clocks, used in the implementation of [time.clock],
186 and of the nanosleep and sched_yield functions, used in the
187 implementation of [thread.thread.this] of the 2011 ISO C++ standard.
188 The choice OPTION=yes checks for the availability of the facilities
189 in libc and libposix4. In case it's needed the latter is also linked
190 to libstdc++ as part of the build process. OPTION=rt also searches
191 (and, if needed, links) librt. Note that the latter is not always
192 desirable because, in glibc, for example, in turn it triggers the
193 linking of libpthread too, which activates locking, a large overhead
194 for single-thread programs. OPTION=no skips the tests completely.
195 The default is OPTION=no.
197 </listitem></varlistentry>
199 <varlistentry><term><code>--enable-libstdcxx-debug</code></term>
200 <listitem><para>Build separate debug libraries in addition to what is normally built.
201 By default, the debug libraries are compiled with
202 <code> CXXFLAGS='-g3 -O0 -fno-inline'</code>
203 , are installed in <code>${libdir}/debug</code>, and have the
204 same names and versioning information as the non-debug
205 libraries. This option is off by default.
207 <para>Note this make command, executed in
208 the build directory, will do much the same thing, without the
209 configuration difference and without building everything twice:
210 <code>make CXXFLAGS='-g3 -O0 -fno-inline' all</code>
212 </listitem></varlistentry>
214 <varlistentry><term><code>--enable-libstdcxx-debug-flags=FLAGS</code></term>
216 <listitem><para>This option is only valid when <code> --enable-debug </code>
217 is also specified, and applies to the debug builds only. With
218 this option, you can pass a specific string of flags to the
219 compiler to use when building the debug versions of libstdc++.
220 FLAGS is a quoted string of options, like
223 --enable-libstdcxx-debug-flags='-g3 -O1 -fno-inline'</programlisting>
224 </listitem></varlistentry>
226 <varlistentry><term><code>--enable-cxx-flags=FLAGS</code></term>
227 <listitem><para>With this option, you can pass a string of -f (functionality)
228 flags to the compiler to use when building libstdc++. This
229 option can change the library ABI. FLAGS is a quoted string of
233 --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</programlisting>
235 Note that the flags don't necessarily have to all be -f flags,
236 as shown, but usually those are the ones that will make sense
237 for experimentation and configure-time overriding.
239 <para>The advantage of --enable-cxx-flags over setting CXXFLAGS in
240 the 'make' environment is that, if files are automatically
241 rebuilt, the same flags will be used when compiling those files
242 as well, so that everything matches.
244 <para>Fun flags to try might include combinations of
250 -fvtable-gc</programlisting>
251 <para>and opposite forms (-fno-) of the same. Tell us (the libstdc++
252 mailing list) if you discover more!
254 </listitem></varlistentry>
256 <varlistentry><term><code>--enable-c99</code></term>
257 <listitem><para>The <type>long long</type> type was introduced in C99, along
258 with many other functions for wide characters, and math
259 classification macros, etc. If enabled, all C99 functions not
260 specified by the C++ standard will be put into <code>namespace
261 __gnu_cxx</code>, and then all these names will
262 be injected into namespace std, so that C99 functions can be
263 used "as if" they were in the C++ standard (as they
264 will eventually be in some future revision of the standard,
265 without a doubt). By default, C99 support is on, assuming the
266 configure probes find all the necessary functions and bits
267 necessary. This option can change the library ABI.
269 </listitem></varlistentry>
271 <varlistentry><term><code>--enable-wchar_t</code>[default]</term>
272 <listitem><para>Template specializations for the <type>wchar_t</type> type are
273 required for wide character conversion support. Disabling
274 wide character specializations may be expedient for initial
275 porting efforts, but builds only a subset of what is required by
276 ISO, and is not recommended. By default, this option is on.
277 This option can change the library ABI.
279 </listitem></varlistentry>
281 <varlistentry><term><code>--enable-long-long </code></term>
282 <listitem><para>The <type>long long</type> type was introduced in C99. It is
283 provided as a GNU extension to C++98 in g++. This flag builds
284 support for "long long" into the library (specialized
285 templates and the like for iostreams). This option is on by default:
286 if enabled, users will have to either use the new-style "C"
287 headers by default (i.e., <cmath> not <math.h>)
288 or add appropriate compile-time flags to all compile lines to
289 allow "C" visibility of this feature (on GNU/Linux,
290 the flag is -D_ISOC99_SOURCE, which is added automatically via
291 CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
292 This option can change the library ABI.
294 </listitem></varlistentry>
296 <varlistentry><term><code>--enable-fully-dynamic-string</code></term>
297 <listitem><para>This option enables a special version of basic_string avoiding
298 the optimization that allocates empty objects in static memory.
299 Mostly useful together with shared memory allocators, see PR
300 libstdc++/16612 for details.
302 </listitem></varlistentry>
304 <varlistentry><term><code>--enable-concept-checks</code></term>
305 <listitem><para>This turns on additional compile-time checks for instantiated
306 library templates, in the form of specialized templates,
307 <link linkend="std.diagnostics.concept_checking">described here</link>. They
308 can help users discover when they break the rules of the STL, before
311 </listitem></varlistentry>
313 <varlistentry><term><code>--enable-symvers[=style]</code></term>
315 <listitem><para>In 3.1 and later, tries to turn on symbol versioning in the
316 shared library (if a shared library has been
317 requested). Values for 'style' that are currently supported
318 are 'gnu', 'gnu-versioned-namespace', 'darwin',
319 'darwin-export', and 'sun'. Both gnu- options require that a recent
320 version of the GNU linker be in use. Both darwin options are
321 equivalent. With no style given, the configure script will try
322 to guess correct defaults for the host system, probe to see if
323 additional requirements are necessary and present for
324 activation, and if so, will turn symbol versioning on. This
325 option can change the library ABI.
328 </listitem></varlistentry>
330 <varlistentry><term><code>--enable-libstdcxx-visibility</code></term>
331 <listitem><para> In 4.2 and later, enables or disables visibility
332 attributes. If enabled (as by default), and the compiler seems
333 capable of passing the simple sanity checks thrown at it, adjusts
334 items in namespace std, namespace std::tr1, namespace std::tr2,
335 and namespace __gnu_cxx to have <code>visibility ("default")</code>
336 so that -fvisibility options can be used without affecting the
337 normal external-visibility of namespace std entities.
338 Prior to 4.7 this option was spelled <code>--enable-visibility</code>.
340 </listitem></varlistentry>
342 <varlistentry><term><code>--enable-libstdcxx-pch</code></term>
343 <listitem><para>In 3.4 and later, tries to turn on the generation of
344 stdc++.h.gch, a pre-compiled file including all the standard
345 C++ includes. If enabled (as by default), and the compiler
346 seems capable of passing the simple sanity checks thrown at
347 it, try to build stdc++.h.gch as part of the make process.
348 In addition, this generated file is used later on (by appending <code>
349 --include bits/stdc++.h </code> to CXXFLAGS) when running the
352 </listitem></varlistentry>
355 <varlistentry><term><code>--enable-extern-template</code>[default]</term>
356 <listitem><para>Use extern template to pre-instantiate all required
357 specializations for certain types defined in the standard libraries.
358 These types include <classname>string</classname> and dependents like
359 <classname>char_traits</classname>, the templatized IO classes,
360 <classname>allocator</classname>, and others.
361 Disabling means that implicit
362 template generation will be used when compiling these types. By
363 default, this option is on. This option can change the library ABI.
365 </listitem></varlistentry>
367 <varlistentry><term><code>--disable-hosted-libstdcxx</code></term>
370 By default, a complete <emphasis>hosted</emphasis> C++ library is
371 built. The C++ Standard also describes a
372 <emphasis>freestanding</emphasis> environment, in which only a
373 minimal set of headers are provided. This option builds such an
376 </listitem></varlistentry>
378 <varlistentry><term><code>--disable-libstdcxx-verbose</code></term>
381 By default, the library is configured to write descriptive messages
382 to standard error for certain events such as calling a pure virtual
383 function or the invocation of the standard terminate handler. Those
384 messages cause the library to depend on the demangler and standard I/O
385 facilites, which might be undesirable in a low-memory environment or
386 when standard error is not available. This option disables those
387 messages. This option does not change the library ABI.
389 </listitem></varlistentry>