libstdc++-v3/doc/xml/manual/configure.xml

   1 <sect1 id="manual.intro.setup.configure" xreflabel="Configuring">
   2 <?dbhtml filename="configure.html"?>
   3
   4 <sect1info>
   5   <keywordset>
   6     <keyword>
   7       ISO C++
   8     </keyword>
   9     <keyword>
  10       configure
  11     </keyword>
  12     <keyword>
  13       options
  14     </keyword>
  15   </keywordset>
  16 </sect1info>
  17
  18 <title>Configure</title>
  19
  20 <para>
  21   When configuring libstdc++, you'll have to configure the entire
  22   <emphasis>gccsrcdir</emphasis> directory. Consider using the
  23   toplevel gcc configuration option
  24   <literal>--enable-languages=c++</literal>, which saves time by only
  25   building the C++ toolchain.
  26 </para>
  27
  28 <para>
  29   Here are all of the configure options specific to libstdc++.  Keep
  30   in mind that
  31    <!-- This SECnn should be the "Choosing Package Options" section. -->
  32    <ulink url="http://sourceware.org/autobook/autobook/autobook_14.html">they
  33    all have opposite forms as well</ulink> (enable/disable and
  34    with/without).  The defaults are for the <emphasis>current
  35    development sources</emphasis>, which may be different than those
  36    for released versions.
  37 </para>
  38 <para>The canonical way to find out the configure options that are
  39    available for a given set of libstdc++ sources is to go to the
  40    source directory and then type:<command>./configure --help</command>.
  41 </para>
  42
  43 <variablelist>
  44  <varlistentry><term><code>--enable-multilib</code>[default]</term>
  45  <listitem><para>This is part of the generic multilib support for building cross
  46         compilers.  As such, targets like &quot;powerpc-elf&quot; will have
  47         libstdc++ built many different ways:  &quot;-msoft-float&quot;
  48         and not, etc.  A different libstdc++ will be built for each of
  49         the different multilib versions.  This option is on by default.
  50      </para>
  51  </listitem></varlistentry>
  52
  53  <varlistentry><term><code>--enable-sjlj-exceptions</code></term>
  54  <listitem><para>Forces old, set-jump/long-jump exception handling model.  If
  55         at all possible, the new, frame unwinding exception handling routines
  56         should be used instead, as they significantly reduce both
  57         runtime memory usage and executable size. This option can
  58         change the library ABI.
  59      </para>
  60  </listitem></varlistentry>
  61
  62  <varlistentry><term><code>--enable-version-specific-runtime-libs</code></term>
  63  <listitem><para>Specify that run-time libraries should be installed in the
  64         compiler-specific subdirectory (i.e.,
  65         <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>)
  66         instead of <code>${libdir}</code>.  This option is useful if you
  67         intend to use several versions of gcc in parallel.  In addition,
  68         libstdc++'s include files will be installed in
  69         <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>,
  70         unless you also specify
  71        <literal>--with-gxx-include-dir=<filename class="directory">dirname</filename></literal> during configuration.
  72      </para>
  73  </listitem></varlistentry>
  74
  75  <varlistentry><term><code>--with-gxx-include-dir=&lt;include-files dir&gt;</code></term>
  76  <listitem><para>Adds support for named libstdc++ include directory.  For instance,
  77         the following puts all the libstdc++ headers into a directory
  78         called &quot;4.4-20090404&quot; instead of the usual
  79         &quot;c++/(version)&quot;.
  80      </para>
  81         <programlisting>
  82    --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/4.4-20090404</programlisting> </listitem></varlistentry>
  83
  84  <varlistentry><term><code>--enable-cstdio</code></term>
  85  <listitem><para>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code>
  86         (described next).
  87      </para>
  88  </listitem></varlistentry>
  89
  90  <varlistentry><term><code>--enable-cstdio=OPTION</code></term>
  91  <listitem><para>Select a target-specific I/O package. At the moment, the only
  92         choice is to use 'stdio', a generic &quot;C&quot; abstraction.
  93         The default is 'stdio'. This option can change the library ABI.
  94      </para>
  95  </listitem></varlistentry>
  96
  97  <varlistentry><term><code>--enable-clocale</code></term>
  98  <listitem><para>This is an abbreviated form of <code>'--enable-clocale=generic'</code>
  99         (described next).
 100      </para>
 101  </listitem></varlistentry>
 102
 103  <varlistentry><term><code>--enable-clocale=OPTION</code></term>
 104  <listitem><para>Select a target-specific underlying locale package.  The
 105         choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix
 106         (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets,
 107         'gnu' to specify a model based on functionality from the GNU C
 108         library (langinfo/iconv/gettext) (from <ulink url="http://sources.redhat.com/glibc/">glibc</ulink>, the GNU C
 109         library), or 'generic' to use a generic &quot;C&quot;
 110         abstraction which consists of &quot;C&quot; locale info.
 111      </para>
 112
 113      <para>If not explicitly specified, the configure proccess tries
 114       to guess the most suitable package from the choices above. The
 115       default is 'generic'. On glibc-based systems of sufficient
 116       vintage (2.2.5 and newer) and capability (with installed DE and
 117       FR locale data), 'gnu' is automatically selected. This option
 118       can change the library ABI.
 119      </para>
 120  </listitem></varlistentry>
 121
 122  <varlistentry><term><code>--enable-libstdcxx-allocator</code></term>
 123  <listitem><para>This is an abbreviated form of
 124         <code>'--enable-libstdcxx-allocator=auto'</code> (described
 125         next).
 126      </para>
 127  </listitem></varlistentry>
 128
 129  <varlistentry><term><code>--enable-libstdcxx-allocator=OPTION  </code></term>
 130  <listitem><para>Select a target-specific underlying std::allocator.  The
 131         choices are 'new' to specify a wrapper for new, 'malloc' to
 132         specify a wrapper for malloc, 'mt' for a fixed power of two allocator,
 133         'pool' for the SGI pooled allocator or 'bitmap' for a bitmap allocator.
 134         See this page for more information on allocator
 135         <link linkend="allocator.ext">extensions</link>. This option
 136         can change the library ABI.
 137      </para>
 138  </listitem></varlistentry>
 139
 140  <varlistentry><term><code>--enable-cheaders=OPTION</code></term>
 141  <listitem><para>This allows the user to define the approach taken for C header
 142         compatibility with C++. Options are c, c_std, and c_global.
 143         These correspond to the source directory's include/c,
 144         include/c_std, and include/c_global, and may also include
 145         include/c_compatibility.  The default is 'c_global'.
 146      </para>
 147  </listitem></varlistentry>
 148
 149  <varlistentry><term><code>--enable-threads</code></term>
 150  <listitem><para>This is an abbreviated form of <code>'--enable-threads=yes'</code>
 151         (described next).
 152      </para>
 153  </listitem></varlistentry>
 154
 155  <varlistentry><term><code>--enable-threads=OPTION</code></term>
 156  <listitem><para>Select a threading library.  A full description is
 157         given in the
 158         general <ulink url="http://gcc.gnu.org/install/configure.html">compiler
 159         configuration instructions</ulink>. This option can change the
 160         library ABI.
 161      </para>
 162  </listitem></varlistentry>
 163
 164  <varlistentry><term><code>--enable-libstdcxx-debug</code></term>
 165  <listitem><para>Build separate debug libraries in addition to what is normally built.
 166         By default, the debug libraries are compiled with
 167         <code> CXXFLAGS='-g3 -O0 -fno-inline'</code>
 168         , are installed in <code>${libdir}/debug</code>, and have the
 169         same names and versioning information as the non-debug
 170         libraries. This option is off by default.
 171      </para>
 172      <para>Note this make command, executed in
 173         the build directory, will do much the same thing, without the
 174         configuration difference and without building everything twice:
 175         <code>make CXXFLAGS='-g3 -O0 -fno-inline' all</code>
 176      </para>
 177  </listitem></varlistentry>
 178
 179  <varlistentry><term><code>--enable-libstdcxx-debug-flags=FLAGS</code></term>
 180
 181  <listitem><para>This option is only valid when <code> --enable-debug </code>
 182         is also specified, and applies to the debug builds only. With
 183         this option, you can pass a specific string of flags to the
 184         compiler to use when building the debug versions of libstdc++.
 185         FLAGS is a quoted string of options, like
 186      </para>
 187         <programlisting>
 188   --enable-libstdcxx-debug-flags='-g3 -O1 -fno-inline'</programlisting>
 189  </listitem></varlistentry>
 190
 191  <varlistentry><term><code>--enable-cxx-flags=FLAGS</code></term>
 192  <listitem><para>With this option, you can pass a string of -f (functionality)
 193         flags to the compiler to use when building libstdc++. This
 194         option can change the library ABI. FLAGS is a quoted string of
 195         options, like
 196      </para>
 197         <programlisting>
 198   --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</programlisting>
 199      <para>
 200         Note that the flags don't necessarily have to all be -f flags,
 201         as shown, but usually those are the ones that will make sense
 202         for experimentation and configure-time overriding.
 203      </para>
 204      <para>The advantage of --enable-cxx-flags over setting CXXFLAGS in
 205         the 'make' environment is that, if files are automatically
 206         rebuilt, the same flags will be used when compiling those files
 207         as well, so that everything matches.
 208      </para>
 209      <para>Fun flags to try might include combinations of
 210      </para>
 211         <programlisting>
 212   -fstrict-aliasing
 213   -fno-exceptions
 214   -ffunction-sections
 215   -fvtable-gc</programlisting>
 216      <para>and opposite forms (-fno-) of the same.  Tell us (the libstdc++
 217         mailing list) if you discover more!
 218      </para>
 219  </listitem></varlistentry>
 220
 221  <varlistentry><term><code>--enable-c99</code></term>
 222  <listitem><para>The &quot;long long&quot; type was introduced in C99, along
 223         with many other functions for wide characters, and math
 224         classification macros, etc.  If enabled, all C99 functions not
 225         specified by the C++ standard will be put into <code>namespace
 226         __gnu_cxx</code>, and then all these names will
 227         be injected into namespace std, so that C99 functions can be
 228         used &quot;as if&quot; they were in the C++ standard (as they
 229         will eventually be in some future revision of the standard,
 230         without a doubt).  By default, C99 support is on, assuming the
 231         configure probes find all the necessary functions and bits
 232         necessary. This option can change the library ABI.
 233     </para>
 234  </listitem></varlistentry>
 235
 236  <varlistentry><term><code>--enable-wchar_t</code>[default]</term>
 237  <listitem><para>Template specializations for the &quot;wchar_t&quot; type are
 238         required for wide character conversion support.  Disabling
 239         wide character specializations may be expedient for initial
 240         porting efforts, but builds only a subset of what is required by
 241         ISO, and is not recommended.  By default, this option is on.
 242         This option can change the library ABI.
 243      </para>
 244  </listitem></varlistentry>
 245
 246  <varlistentry><term><code>--enable-long-long  </code></term>
 247  <listitem><para>The &quot;long long&quot; type was introduced in C99.  It is
 248         provided as a GNU extension to C++98 in g++.  This flag builds
 249         support for &quot;long long&quot; into the library (specialized
 250         templates and the like for iostreams).  This option is on by default:
 251         if enabled, users will have to either use the new-style &quot;C&quot;
 252         headers by default (i.e., &lt;cmath&gt; not &lt;math.h&gt;)
 253         or add appropriate compile-time flags to all compile lines to
 254         allow &quot;C&quot; visibility of this feature (on GNU/Linux,
 255         the flag is -D_ISOC99_SOURCE, which is added automatically via
 256         CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
 257         This option can change the library ABI.
 258      </para>
 259  </listitem></varlistentry>
 260
 261  <varlistentry><term><code>--enable-fully-dynamic-string</code></term>
 262  <listitem><para>This option enables a special version of basic_string avoiding
 263         the optimization that allocates empty objects in static memory.
 264         Mostly useful together with shared memory allocators, see PR
 265         libstdc++/16612 for details.
 266      </para>
 267  </listitem></varlistentry>
 268
 269  <varlistentry><term><code>--enable-concept-checks</code></term>
 270  <listitem><para>This turns on additional compile-time checks for instantiated
 271         library templates, in the form of specialized templates,
 272         <link linkend="manual.diagnostics.concept_checking">described here</link>.  They
 273         can help users discover when they break the rules of the STL, before
 274         their programs run.
 275      </para>
 276  </listitem></varlistentry>
 277
 278  <varlistentry><term><code>--enable-symvers[=style]</code></term>
 279
 280  <listitem><para>In 3.1 and later, tries to turn on symbol versioning in the
 281         shared library (if a shared library has been
 282         requested). Values for 'style' that are currently supported
 283         are 'gnu', 'gnu-versioned-namespace', 'darwin', and
 284         'darwin-export'. Both gnu- options require that a recent
 285         version of the GNU linker be in use. Both darwin options are
 286         equivalent. With no style given, the configure script will try
 287         to guess correct defaults for the host system, probe to see if
 288         additional requirements are necessary and present for
 289         activation, and if so, will turn symbol versioning on. This
 290         option can change the library ABI.
 291      </para>
 292
 293  </listitem></varlistentry>
 294
 295  <varlistentry><term><code>--enable-visibility</code></term>
 296  <listitem><para> In 4.2 and later, enables or disables visibility attributes.
 297         If enabled (as by default), and the compiler seems capable of
 298         passing the simple sanity checks thrown at it, adjusts items
 299         in namespace std, namespace std::tr1, and namespace __gnu_cxx
 300         so that -fvisibility options work.
 301     </para>
 302  </listitem></varlistentry>
 303
 304  <varlistentry><term><code>--enable-libstdcxx-pch</code></term>
 305  <listitem><para>In 3.4 and later, tries to turn on the generation of
 306         stdc++.h.gch, a pre-compiled file including all the standard
 307         C++ includes. If enabled (as by default), and the compiler
 308         seems capable of passing the simple sanity checks thrown at
 309         it, try to build stdc++.h.gch as part of the make process.
 310         In addition, this generated file is used later on (by appending <code>
 311         --include bits/stdc++.h </code> to CXXFLAGS) when running the
 312         testsuite.
 313      </para>
 314  </listitem></varlistentry>
 315
 316  <varlistentry><term><code>--disable-hosted-libstdcxx</code></term>
 317  <listitem>
 318    <para>
 319      By default, a complete <emphasis>hosted</emphasis> C++ library is
 320      built.  The C++ Standard also describes a
 321      <emphasis>freestanding</emphasis> environment, in which only a
 322      minimal set of headers are provided.  This option builds such an
 323      environment.
 324      </para>
 325  </listitem></varlistentry>
 326
 327  <varlistentry><term><code>--enable-clock-gettime</code></term>
 328  <listitem><para>This is an abbreviated form of
 329         <code>'--enable-clock-gettime=yes'</code>(described next).
 330      </para>
 331  </listitem></varlistentry>
 332
 333  <varlistentry><term><code>--enable-libstdcxx-time=OPTION</code></term>
 334  <listitem><para>Enables link-type checks for the availability of the
 335         clock_gettime clocks, used in the implementation of [time.clock],
 336         and of the nanosleep and sched_yield functions, used in the
 337         implementation of [thread.thread.this] of the current C++0x draft.
 338         The choice OPTION=yes checks for the availability of the facilities
 339         in libc and libposix4.  In case of need the latter is also linked
 340         to libstdc++ as part of the build process.  OPTION=rt also searches
 341         (and, in case, links) librt.   Note that the latter is not always
 342         desirable because, in glibc, for example, in turn it triggers the
 343         linking of libpthread too, which activates locking, a large overhead
 344         for single-thread programs.  OPTION=no skips the tests completely.
 345         The default is OPTION=no.
 346     </para>
 347  </listitem></varlistentry>
 348
 349 </variablelist>
 350
 351 </sect1>