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>
7 <keyword>ISO C++</keyword>
8 <keyword>configure</keyword>
9 <keyword>options</keyword>
16 When configuring libstdc++, you'll have to configure the entire
17 <emphasis>gccsrcdir</emphasis> directory. Consider using the
18 toplevel gcc configuration option
19 <literal>--enable-languages=c++</literal>, which saves time by only
20 building the C++ toolchain.
24 Here are all of the configure options specific to libstdc++. Keep
26 <!-- This SECnn should be the "Choosing Package Options" section. -->
27 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/autobook/autobook/autobook_14.html">they
28 all have opposite forms as well</link> (enable/disable and
29 with/without). The defaults are for the <emphasis>current
30 development sources</emphasis>, which may be different than those
31 for released versions.
33 <para>The canonical way to find out the configure options that are
34 available for a given set of libstdc++ sources is to go to the
35 source directory and then type: <command>./configure --help</command>.
39 <varlistentry><term><code>--enable-multilib</code>[default]</term>
40 <listitem><para>This is part of the generic multilib support for building cross
41 compilers. As such, targets like "powerpc-elf" will have
42 libstdc++ built many different ways: "-msoft-float"
43 and not, etc. A different libstdc++ will be built for each of
44 the different multilib versions. This option is on by default.
46 </listitem></varlistentry>
48 <varlistentry><term><code>--enable-version-specific-runtime-libs</code></term>
49 <listitem><para>Specify that run-time libraries should be installed in the
50 compiler-specific subdirectory (i.e.,
51 <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>)
52 instead of <code>${libdir}</code>. This option is useful if you
53 intend to use several versions of gcc in parallel. In addition,
54 libstdc++'s include files will be installed in
55 <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>,
56 unless you also specify
57 <literal>--with-gxx-include-dir=</literal><filename class="directory">dirname</filename> during configuration.
59 </listitem></varlistentry>
61 <varlistentry><term><code>--with-gxx-include-dir=<include-files dir></code></term>
62 <listitem><para>Adds support for named libstdc++ include directory. For instance,
63 the following puts all the libstdc++ headers into a directory
64 called "4.4-20090404" instead of the usual
68 --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/4.4-20090404</programlisting> </listitem></varlistentry>
70 <varlistentry><term><code>--enable-cstdio</code></term>
71 <listitem><para>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code>
74 </listitem></varlistentry>
76 <varlistentry><term><code>--enable-cstdio=OPTION</code></term>
77 <listitem><para>Select a target-specific I/O package. At the moment, the only
78 choice is to use 'stdio', a generic "C" abstraction.
79 The default is 'stdio'. This option can change the library ABI.
81 </listitem></varlistentry>
83 <varlistentry><term><code>--enable-clocale</code></term>
84 <listitem><para>This is an abbreviated form of <code>'--enable-clocale=generic'</code>
87 </listitem></varlistentry>
89 <varlistentry><term><code>--enable-clocale=OPTION</code></term>
90 <listitem><para>Select a target-specific underlying locale package. The
91 choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix
92 (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets,
93 'gnu' to specify a model based on functionality from the GNU C
94 library (langinfo/iconv/gettext) (from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/software/libc/">glibc</link>, the GNU C
95 library), 'generic' to use a generic "C" abstraction which consists
96 of "C" locale info, 'newlib' to specify the Newlib C library model
97 which only differs from the 'generic' model in the handling of
98 ctype, or 'darwin' which omits the <type>wchar_t</type> specializations
99 needed by the 'generic' model.
102 <para>If not explicitly specified, the configure process tries
103 to guess the most suitable package from the choices above. The
104 default is 'generic'. On glibc-based systems of sufficient
105 vintage (2.3 and newer), 'gnu' is automatically selected. On newlib-based
106 systems (<code>'--with_newlib=yes'</code>) and OpenBSD, 'newlib' is
107 automatically selected. On Mac OS X 'darwin' is automatically selected.
108 This option can change the library ABI.
110 </listitem></varlistentry>
112 <varlistentry><term><code>--enable-libstdcxx-allocator</code></term>
113 <listitem><para>This is an abbreviated form of
114 <code>'--enable-libstdcxx-allocator=auto'</code> (described
117 </listitem></varlistentry>
119 <varlistentry><term><code>--enable-libstdcxx-allocator=OPTION </code></term>
120 <listitem><para>Select a target-specific underlying std::allocator. The
121 choices are 'new' to specify a wrapper for new, 'malloc' to
122 specify a wrapper for malloc, 'mt' for a fixed power of two allocator,
123 'pool' for the SGI pooled allocator or 'bitmap' for a bitmap allocator.
124 See this page for more information on allocator
125 <link linkend="allocator.ext">extensions</link>. This option
126 can change the library ABI.
128 </listitem></varlistentry>
130 <varlistentry><term><code>--enable-cheaders=OPTION</code></term>
131 <listitem><para>This allows the user to define the approach taken for C header
132 compatibility with C++. Options are c, c_std, and c_global.
133 These correspond to the source directory's include/c,
134 include/c_std, and include/c_global, and may also include
135 include/c_compatibility. The default is 'c_global'.
137 </listitem></varlistentry>
139 <varlistentry><term><code>--enable-threads</code></term>
140 <listitem><para>This is an abbreviated form of <code>'--enable-threads=yes'</code>
143 </listitem></varlistentry>
145 <varlistentry><term><code>--enable-threads=OPTION</code></term>
146 <listitem><para>Select a threading library. A full description is
148 general <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/configure.html">compiler
149 configuration instructions</link>. This option can change the
152 </listitem></varlistentry>
154 <varlistentry><term><code>--enable-libstdcxx-threads</code></term>
155 <listitem><para>Enable C++11 threads support. If not explicitly specified,
156 the configure process enables it if possible. This
157 option can change the library ABI.
159 </listitem></varlistentry>
161 <varlistentry><term><code>--enable-libstdcxx-time</code></term>
162 <listitem><para>This is an abbreviated form of
163 <code>'--enable-libstdcxx-time=yes'</code>(described next).
165 </listitem></varlistentry>
167 <varlistentry><term><code>--enable-libstdcxx-time=OPTION</code></term>
168 <listitem><para>Enables link-type checks for the availability of the
169 clock_gettime clocks, used in the implementation of [time.clock],
170 and of the nanosleep and sched_yield functions, used in the
171 implementation of [thread.thread.this] of the 2011 ISO C++ standard.
172 The choice OPTION=yes checks for the availability of the facilities
173 in libc and libposix4. In case it's needed the latter is also linked
174 to libstdc++ as part of the build process. OPTION=rt also searches
175 (and, if needed, links) librt. Note that the latter is not always
176 desirable because, in glibc, for example, in turn it triggers the
177 linking of libpthread too, which activates locking, a large overhead
178 for single-thread programs. OPTION=no skips the tests completely.
179 The default is OPTION=auto, which skips the checks and enables the
180 features only for targets known to support them.
182 </listitem></varlistentry>
184 <varlistentry><term><code>--enable-libstdcxx-debug</code></term>
185 <listitem><para>Build separate debug libraries in addition to what is normally built.
186 By default, the debug libraries are compiled with
187 <code> CXXFLAGS='-g3 -O0 -fno-inline'</code>
188 , are installed in <code>${libdir}/debug</code>, and have the
189 same names and versioning information as the non-debug
190 libraries. This option is off by default.
192 <para>Note this make command, executed in
193 the build directory, will do much the same thing, without the
194 configuration difference and without building everything twice:
195 <code>make CXXFLAGS='-g3 -O0 -fno-inline' all</code>
197 </listitem></varlistentry>
199 <varlistentry><term><code>--enable-libstdcxx-debug-flags=FLAGS</code></term>
201 <listitem><para>This option is only valid when <code> --enable-debug </code>
202 is also specified, and applies to the debug builds only. With
203 this option, you can pass a specific string of flags to the
204 compiler to use when building the debug versions of libstdc++.
205 FLAGS is a quoted string of options, like
208 --enable-libstdcxx-debug-flags='-g3 -O1 -fno-inline'</programlisting>
209 </listitem></varlistentry>
211 <varlistentry><term><code>--enable-cxx-flags=FLAGS</code></term>
212 <listitem><para>With this option, you can pass a string of -f (functionality)
213 flags to the compiler to use when building libstdc++. This
214 option can change the library ABI. FLAGS is a quoted string of
218 --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</programlisting>
220 Note that the flags don't necessarily have to all be -f flags,
221 as shown, but usually those are the ones that will make sense
222 for experimentation and configure-time overriding.
224 <para>The advantage of --enable-cxx-flags over setting CXXFLAGS in
225 the 'make' environment is that, if files are automatically
226 rebuilt, the same flags will be used when compiling those files
227 as well, so that everything matches.
229 <para>Fun flags to try might include combinations of
235 -fvtable-gc</programlisting>
236 <para>and opposite forms (-fno-) of the same. Tell us (the libstdc++
237 mailing list) if you discover more!
239 </listitem></varlistentry>
241 <varlistentry><term><code>--enable-c99</code></term>
242 <listitem><para>The <type>long long</type> type was introduced in C99, along
243 with many other functions for wide characters, and math
244 classification macros, etc. If enabled, all C99 functions not
245 specified by the C++ standard will be put into <code>namespace
246 __gnu_cxx</code>, and then all these names will
247 be injected into namespace std, so that C99 functions can be
248 used "as if" they were in the C++ standard (as they
249 will eventually be in some future revision of the standard,
250 without a doubt). By default, C99 support is on, assuming the
251 configure probes find all the necessary functions and bits
252 necessary. This option can change the library ABI.
254 </listitem></varlistentry>
256 <varlistentry><term><code>--enable-wchar_t</code>[default]</term>
257 <listitem><para>Template specializations for the <type>wchar_t</type> type are
258 required for wide character conversion support. Disabling
259 wide character specializations may be expedient for initial
260 porting efforts, but builds only a subset of what is required by
261 ISO, and is not recommended. By default, this option is on.
262 This option can change the library ABI.
264 </listitem></varlistentry>
266 <varlistentry><term><code>--enable-long-long </code></term>
267 <listitem><para>The <type>long long</type> type was introduced in C99. It is
268 provided as a GNU extension to C++98 in g++. This flag builds
269 support for "long long" into the library (specialized
270 templates and the like for iostreams). This option is on by default:
271 if enabled, users will have to either use the new-style "C"
272 headers by default (i.e., <cmath> not <math.h>)
273 or add appropriate compile-time flags to all compile lines to
274 allow "C" visibility of this feature (on GNU/Linux,
275 the flag is -D_ISOC99_SOURCE, which is added automatically via
276 CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
277 This option can change the library ABI.
279 </listitem></varlistentry>
281 <varlistentry><term><code>--enable-fully-dynamic-string</code></term>
282 <listitem><para>This option enables a special version of basic_string avoiding
283 the optimization that allocates empty objects in static memory.
284 Mostly useful together with shared memory allocators, see PR
285 libstdc++/16612 for details.
287 </listitem></varlistentry>
289 <varlistentry><term><code>--enable-concept-checks</code></term>
290 <listitem><para>This turns on additional compile-time checks for instantiated
291 library templates, in the form of specialized templates described in
292 the <link linkend="std.diagnostics.concept_checking">Concept
293 Checking</link> section. They
294 can help users discover when they break the rules of the STL, before
295 their programs run. These checks are based on C++03 rules and some of
296 them are not compatible with correct C++11 code.
298 </listitem></varlistentry>
300 <varlistentry><term><code>--enable-symvers[=style]</code></term>
302 <listitem><para>In 3.1 and later, tries to turn on symbol versioning in the
303 shared library (if a shared library has been
304 requested). Values for 'style' that are currently supported
305 are 'gnu', 'gnu-versioned-namespace', 'darwin',
306 'darwin-export', and 'sun'. Both gnu- options require that a recent
307 version of the GNU linker be in use. Both darwin options are
308 equivalent. With no style given, the configure script will try
309 to guess correct defaults for the host system, probe to see if
310 additional requirements are necessary and present for
311 activation, and if so, will turn symbol versioning on. This
312 option can change the library ABI.
315 </listitem></varlistentry>
317 <varlistentry><term><code>--enable-libstdcxx-visibility</code></term>
318 <listitem><para> In 4.2 and later, enables or disables visibility
319 attributes. If enabled (as by default), and the compiler seems
320 capable of passing the simple sanity checks thrown at it, adjusts
321 items in namespace std, namespace std::tr1, namespace std::tr2,
322 and namespace __gnu_cxx to have <code>visibility ("default")</code>
323 so that -fvisibility options can be used without affecting the
324 normal external-visibility of namespace std entities.
325 Prior to 4.7 this option was spelled <code>--enable-visibility</code>.
327 </listitem></varlistentry>
329 <varlistentry><term><code>--enable-libstdcxx-pch</code></term>
330 <listitem><para>In 3.4 and later, tries to turn on the generation of
331 stdc++.h.gch, a pre-compiled file including all the standard
332 C++ includes. If enabled (as by default), and the compiler
333 seems capable of passing the simple sanity checks thrown at
334 it, try to build stdc++.h.gch as part of the make process.
335 In addition, this generated file is used later on (by appending <code>
336 --include bits/stdc++.h </code> to CXXFLAGS) when running the
339 </listitem></varlistentry>
342 <varlistentry><term><code>--enable-extern-template</code>[default]</term>
343 <listitem><para>Use extern template to pre-instantiate all required
344 specializations for certain types defined in the standard libraries.
345 These types include <classname>string</classname> and dependents like
346 <classname>char_traits</classname>, the templatized IO classes,
347 <classname>allocator</classname>, and others.
348 Disabling means that implicit
349 template generation will be used when compiling these types. By
350 default, this option is on. This option can change the library ABI.
352 </listitem></varlistentry>
354 <varlistentry><term><code>--disable-hosted-libstdcxx</code></term>
357 By default, a complete <emphasis>hosted</emphasis> C++ library is
358 built. The C++ Standard also describes a
359 <emphasis>freestanding</emphasis> environment, in which only a
360 minimal set of headers are provided. This option builds such an
363 </listitem></varlistentry>
365 <varlistentry><term><code>--disable-libstdcxx-verbose</code></term>
368 By default, the library is configured to write descriptive messages
369 to standard error for certain events such as calling a pure virtual
370 function or the invocation of the standard terminate handler. Those
371 messages cause the library to depend on the demangler and standard I/O
372 facilities, which might be undesirable in a low-memory environment or
373 when standard error is not available. This option disables those
374 messages. This option does not change the library ABI.
376 </listitem></varlistentry>
378 <varlistentry><term><code>--disable-libstdcxx-dual-abi</code></term>
381 Disable support for the new, C++11-conforming implementations of
382 <code>std::string</code>, <code>std::list</code> etc. so that the
383 library only provides definitions of types using the old ABI
384 (see <xref linkend="manual.intro.using.abi"/>).
385 This option changes the library ABI.
387 </listitem></varlistentry>
389 <varlistentry><term><code>--with-default-libstdcxx-abi=</code><replaceable>OPTION</replaceable></term>
392 Set the default value for the <symbol>_GLIBCXX_USE_CXX11_ABI</symbol>
393 macro (see <xref linkend="manual.intro.using.macros"/>).
394 The default is <option>OPTION=new</option> which sets the macro to
395 <literal>1</literal>,
396 use <option>OPTION=gcc4-compatible</option> to set it to
397 <literal>0</literal>.
398 This option does not change the library ABI.
400 </listitem></varlistentry>
402 <varlistentry><term><code>--enable-vtable-verify</code>[default]</term>
404 <para>Use <code>-fvtable-verify=std</code> to compile the C++
405 runtime with instrumentation for vtable verification. All virtual
406 functions in the standard library will be verified at runtime.
407 Types impacted include <classname>locale</classname> and
408 <classname>iostream</classname>, and others. Disabling means that
409 the C++ runtime is compiled without support for vtable
410 verification. By default, this option is off.
412 </listitem></varlistentry>
414 <varlistentry><term><code>--enable-libstdcxx-filesystem-ts</code>[default]</term>
416 <para>Build <filename class="libraryfile">libstdc++fs.a</filename> as well
417 as the usual libstdc++ and libsupc++ libraries. This is enabled by
418 default on select POSIX targets where it is known to work and disabled
421 </listitem></varlistentry>