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"?> 4 5<info><title>Configure</title> 6 <keywordset> 7 <keyword>ISO C++</keyword> 8 <keyword>configure</keyword> 9 <keyword>options</keyword> 10 </keywordset> 11</info> 12 13 14 15<para> 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. 21</para> 22 23<para> 24 Here are all of the configure options specific to libstdc++. Keep 25 in mind that 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. 32</para> 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>. 36</para> 37 38<variablelist> 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. 45 </para> 46 </listitem></varlistentry> 47 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. 58 </para> 59 </listitem></varlistentry> 60 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 65 "c++/(version)". 66 </para> 67 <programlisting> 68 --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/4.4-20090404</programlisting> </listitem></varlistentry> 69 70 <varlistentry><term><code>--enable-cstdio</code></term> 71 <listitem><para>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code> 72 (described next). 73 </para> 74 </listitem></varlistentry> 75 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. 80 </para> 81 </listitem></varlistentry> 82 83 <varlistentry><term><code>--enable-clocale</code></term> 84 <listitem><para>This is an abbreviated form of <code>'--enable-clocale=generic'</code> 85 (described next). 86 </para> 87 </listitem></varlistentry> 88 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. 100 </para> 101 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. 109 </para> 110 </listitem></varlistentry> 111 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 115 next). 116 </para> 117 </listitem></varlistentry> 118 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. 127 </para> 128 </listitem></varlistentry> 129 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'. 136 </para> 137 </listitem></varlistentry> 138 139 <varlistentry><term><code>--enable-threads</code></term> 140 <listitem><para>This is an abbreviated form of <code>'--enable-threads=yes'</code> 141 (described next). 142 </para> 143 </listitem></varlistentry> 144 145 <varlistentry><term><code>--enable-threads=OPTION</code></term> 146 <listitem><para>Select a threading library. A full description is 147 given in the 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 150 library ABI. 151 </para> 152 </listitem></varlistentry> 153 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. 158 </para> 159 </listitem></varlistentry> 160 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). 164 </para> 165 </listitem></varlistentry> 166 167 <varlistentry><term><code>--enable-libstdcxx-time=OPTION</code></term> 168 <listitem><para>Enables link-type checks for the availability of the 169 <function>clock_gettime</function> clocks, used in the implementation 170 of [time.clock], and of the <function>nanosleep</function> and 171 <function>sched_yield</function> functions, used in the 172 implementation of [thread.thread.this] of the 2011 ISO C++ standard. 173 The choice OPTION=yes checks for the availability of the facilities 174 in libc. OPTION=rt also checks in 175 librt (and, if it's needed, links to it). Note that linking to librt 176 is not always desirable because for glibc it requires linking to 177 libpthread too, which causes all reference counting to use atomic 178 operations, resulting in a potentially large overhead for 179 single-threaded programs. OPTION=no skips the tests completely. 180 The default is OPTION=auto, which skips the checks and enables the 181 features only for targets known to support them. 182 For Linux targets, if <function>clock_gettime</function> is not used 183 then the [time.clock] implementation will use a system call to access 184 the realtime and monotonic clocks, which is significantly slower than 185 the C library's <function>clock_gettime</function> function. 186 </para> 187 </listitem></varlistentry> 188 189 <varlistentry><term><code>--enable-libstdcxx-debug</code></term> 190 <listitem><para>Build separate debug libraries in addition to what is normally built. 191 By default, the debug libraries are compiled with 192 <code> CXXFLAGS='-g3 -O0 -fno-inline'</code> 193 , are installed in <code>${libdir}/debug</code>, and have the 194 same names and versioning information as the non-debug 195 libraries. This option is off by default. 196 </para> 197 <para>Note this make command, executed in 198 the build directory, will do much the same thing, without the 199 configuration difference and without building everything twice: 200 <code>make CXXFLAGS='-g3 -O0 -fno-inline' all</code> 201 </para> 202 </listitem></varlistentry> 203 204 <varlistentry><term><code>--enable-libstdcxx-debug-flags=FLAGS</code></term> 205 206 <listitem><para>This option is only valid when 207 <code>--enable-libstdcxx-debug</code> 208 is also specified, and applies to the debug builds only. With 209 this option, you can pass a specific string of flags to the 210 compiler to use when building the debug versions of libstdc++. 211 FLAGS is a quoted string of options, like 212 </para> 213 <programlisting> 214 --enable-libstdcxx-debug-flags='-g3 -O1 -fno-inline'</programlisting> 215 </listitem></varlistentry> 216 217 <varlistentry><term><code>--enable-cxx-flags=FLAGS</code></term> 218 <listitem><para>With this option, you can pass a string of -f (functionality) 219 flags to the compiler to use when building libstdc++. This 220 option can change the library ABI. FLAGS is a quoted string of 221 options, like 222 </para> 223 <programlisting> 224 --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</programlisting> 225 <para> 226 Note that the flags don't necessarily have to all be -f flags, 227 as shown, but usually those are the ones that will make sense 228 for experimentation and configure-time overriding. 229 </para> 230 <para>The advantage of --enable-cxx-flags over setting CXXFLAGS in 231 the 'make' environment is that, if files are automatically 232 rebuilt, the same flags will be used when compiling those files 233 as well, so that everything matches. 234 </para> 235 <para>Fun flags to try might include combinations of 236 </para> 237 <programlisting> 238 -fstrict-aliasing 239 -fno-exceptions 240 -ffunction-sections 241 -fvtable-gc</programlisting> 242 <para>and opposite forms (-fno-) of the same. Tell us (the libstdc++ 243 mailing list) if you discover more! 244 </para> 245 </listitem></varlistentry> 246 247 <varlistentry><term><code>--enable-c99</code></term> 248 <listitem><para>The <type>long long</type> type was introduced in C99, along 249 with many other functions for wide characters, and math 250 classification macros, etc. If enabled, all C99 functions not 251 specified by the C++ standard will be put into <code>namespace 252 __gnu_cxx</code>, and then all these names will 253 be injected into namespace std, so that C99 functions can be 254 used "as if" they were in the C++ standard (as they 255 will eventually be in some future revision of the standard, 256 without a doubt). By default, C99 support is on, assuming the 257 configure probes find all the necessary functions and bits 258 necessary. This option can change the library ABI. 259 </para> 260 </listitem></varlistentry> 261 262 <varlistentry><term><code>--enable-wchar_t</code>[default]</term> 263 <listitem><para>Template specializations for the <type>wchar_t</type> type are 264 required for wide character conversion support. Disabling 265 wide character specializations may be expedient for initial 266 porting efforts, but builds only a subset of what is required by 267 ISO, and is not recommended. By default, this option is on. 268 This option can change the library ABI. 269 </para> 270 </listitem></varlistentry> 271 272 <varlistentry><term><code>--enable-long-long </code></term> 273 <listitem><para>The <type>long long</type> type was introduced in C99. It is 274 provided as a GNU extension to C++98 in g++. This flag builds 275 support for "long long" into the library (specialized 276 templates and the like for iostreams). This option is on by default: 277 if enabled, users will have to either use the new-style "C" 278 headers by default (i.e., <cmath> not <math.h>) 279 or add appropriate compile-time flags to all compile lines to 280 allow "C" visibility of this feature (on GNU/Linux, 281 the flag is -D_ISOC99_SOURCE, which is added automatically via 282 CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE). 283 This option can change the library ABI. 284 </para> 285 </listitem></varlistentry> 286 287 <varlistentry><term><code>--enable-fully-dynamic-string</code></term> 288 <listitem><para>This option enables a special version of basic_string avoiding 289 the optimization that allocates empty objects in static memory. 290 Mostly useful together with shared memory allocators, see PR 291 libstdc++/16612 for details. 292 </para> 293 </listitem></varlistentry> 294 295 <varlistentry><term><code>--enable-concept-checks</code></term> 296 <listitem><para>This turns on additional compile-time checks for instantiated 297 library templates, in the form of specialized templates described in 298 the <link linkend="std.diagnostics.concept_checking">Concept 299 Checking</link> section. They 300 can help users discover when they break the rules of the STL, before 301 their programs run. These checks are based on C++03 rules and some of 302 them are not compatible with correct C++11 code. 303 </para> 304 </listitem></varlistentry> 305 306 <varlistentry><term><code>--enable-symvers[=style]</code></term> 307 308 <listitem><para>In 3.1 and later, tries to turn on symbol versioning in the 309 shared library (if a shared library has been 310 requested). Values for 'style' that are currently supported 311 are 'gnu', 'gnu-versioned-namespace', 'darwin', 312 'darwin-export', and 'sun'. Both gnu- options require that a recent 313 version of the GNU linker be in use. Both darwin options are 314 equivalent. With no style given, the configure script will try 315 to guess correct defaults for the host system, probe to see if 316 additional requirements are necessary and present for 317 activation, and if so, will turn symbol versioning on. This 318 option can change the library ABI. 319 </para> 320 321 </listitem></varlistentry> 322 323 <varlistentry><term><code>--enable-libstdcxx-visibility</code></term> 324 <listitem><para> In 4.2 and later, enables or disables visibility 325 attributes. If enabled (as by default), and the compiler seems 326 capable of passing the simple sanity checks thrown at it, adjusts 327 items in namespace std, namespace std::tr1, namespace std::tr2, 328 and namespace __gnu_cxx to have <code>visibility ("default")</code> 329 so that -fvisibility options can be used without affecting the 330 normal external-visibility of namespace std entities. 331 Prior to 4.7 this option was spelled <code>--enable-visibility</code>. 332 </para> 333 </listitem></varlistentry> 334 335 <varlistentry><term><code>--enable-libstdcxx-pch</code></term> 336 <listitem><para>In 3.4 and later, tries to turn on the generation of 337 stdc++.h.gch, a pre-compiled file including all the standard 338 C++ includes. If enabled (as by default), and the compiler 339 seems capable of passing the simple sanity checks thrown at 340 it, try to build stdc++.h.gch as part of the make process. 341 In addition, this generated file is used later on (by appending <code> 342 --include bits/stdc++.h </code> to CXXFLAGS) when running the 343 testsuite. 344 </para> 345 </listitem></varlistentry> 346 347 348 <varlistentry><term><code>--enable-extern-template</code>[default]</term> 349 <listitem><para>Use extern template to pre-instantiate all required 350 specializations for certain types defined in the standard libraries. 351 These types include <classname>string</classname> and dependents like 352 <classname>char_traits</classname>, the templatized IO classes, 353 <classname>allocator</classname>, and others. 354 Disabling means that implicit 355 template generation will be used when compiling these types. By 356 default, this option is on. This option can change the library ABI. 357 </para> 358 </listitem></varlistentry> 359 360 <varlistentry><term><code>--disable-hosted-libstdcxx</code></term> 361 <listitem> 362 <para> 363 By default, a complete <emphasis>hosted</emphasis> C++ library is 364 built. The C++ Standard also describes a 365 <emphasis>freestanding</emphasis> environment, in which only a 366 minimal set of headers are provided. This option builds such an 367 environment. 368 </para> 369 </listitem></varlistentry> 370 371<varlistentry><term><code>--disable-libstdcxx-verbose</code></term> 372 <listitem> 373 <para> 374 By default, the library is configured to write descriptive messages 375 to standard error for certain events such as calling a pure virtual 376 function or the invocation of the standard terminate handler. Those 377 messages cause the library to depend on the demangler and standard I/O 378 facilities, which might be undesirable in a low-memory environment or 379 when standard error is not available. This option disables those 380 messages. This option does not change the library ABI. 381 </para> 382 </listitem></varlistentry> 383 384<varlistentry><term><code>--disable-libstdcxx-dual-abi</code></term> 385 <listitem> 386 <para> 387 Disable support for the new, C++11-conforming implementations of 388 <code>std::string</code>, <code>std::list</code> etc. so that the 389 library only provides definitions of types using the old ABI 390 (see <xref linkend="manual.intro.using.abi"/>). 391 This option changes the library ABI. 392 </para> 393 </listitem></varlistentry> 394 395<varlistentry><term><code>--with-default-libstdcxx-abi=</code><replaceable>OPTION</replaceable></term> 396 <listitem> 397 <para> 398 Set the default value for the <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> 399 macro (see <xref linkend="manual.intro.using.macros"/>). 400 The default is <option>OPTION=new</option> which sets the macro to 401 <literal>1</literal>, 402 use <option>OPTION=gcc4-compatible</option> to set it to 403 <literal>0</literal>. 404 This option does not change the library ABI. 405 </para> 406 </listitem></varlistentry> 407 408 <varlistentry><term><code>--with-libstdcxx-lock-policy=OPTION</code></term> 409 <listitem><para>Sets the lock policy that controls how 410 <classname>shared_ptr</classname> reference counting is 411 synchronized. 412 The choice OPTION=atomic enables use of atomics for updates to 413 <classname>shared_ptr</classname> reference counts. 414 The choice OPTION=mutex enables use of a mutex to synchronize updates 415 to <classname>shared_ptr</classname> reference counts. 416 If the compiler's thread model is "single" then this option has no 417 effect, as no synchronization is used for the reference counts. 418 The default is OPTION=auto, which checks for the availability of 419 compiler built-ins for 2-byte and 4-byte atomic compare-and-swap, 420 and uses OPTION=atomic if they're available, OPTION=mutex otherwise. 421 This option can change the library ABI. 422 If the library is configured to use atomics and user programs are 423 compiled using a target that doesn't natively support the atomic 424 operations (e.g. the library is configured for armv7 and then code 425 is compiled with <option>-march=armv5t</option>) then the program 426 might rely on support in libgcc to provide the atomics. 427 </para> 428 </listitem></varlistentry> 429 430 <varlistentry><term><code>--enable-vtable-verify</code>[default]</term> 431 <listitem> 432 <para>Use <code>-fvtable-verify=std</code> to compile the C++ 433 runtime with instrumentation for vtable verification. All virtual 434 functions in the standard library will be verified at runtime. 435 Types impacted include <classname>locale</classname> and 436 <classname>iostream</classname>, and others. Disabling means that 437 the C++ runtime is compiled without support for vtable 438 verification. By default, this option is off. 439 </para> 440 </listitem></varlistentry> 441 442 <varlistentry><term><code>--enable-libstdcxx-filesystem-ts</code>[default]</term> 443 <listitem> 444 <para>Build <filename class="libraryfile">libstdc++fs.a</filename> as well 445 as the usual libstdc++ and libsupc++ libraries. This is enabled by 446 default on select POSIX targets where it is known to work and disabled 447 otherwise. 448 </para> 449 </listitem></varlistentry> 450 451</variablelist> 452 453</section> 454