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

   1 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
   2          xml:id="manual.intro.setup.prereq" xreflabel="Prerequisites">
   3 <?dbhtml filename="prerequisites.html"?>
   4
   5 <info><title>Prerequisites</title>
   6   <keywordset>
   7     <keyword>ISO C++</keyword>
   8     <keyword>Prerequisites</keyword>
   9   </keywordset>
  10 </info>
  11
  12
  13
  14 <para>
  15   Because libstdc++ is part of GCC, the primary source for
  16    installation instructions is
  17    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/install/">the GCC install page</link>.
  18    In particular, list of prerequisite software needed to build the library
  19    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/install/prerequisites.html">
  20    starts with those requirements.</link> The same pages also list
  21    the tools you will need if you wish to modify the source.
  22 </para>
  23
  24   <para>
  25    Additional data is given here only where it applies to libstdc++.
  26   </para>
  27
  28    <para>To take full advantage of useful space-saving features and
  29       bug-fixes you should use a recent binutils whenever possible.
  30       The configure process will automatically detect and use these
  31       features if the underlying support is present.
  32    </para>
  33
  34    <para>
  35      To generate the API documentation from the sources you will need
  36      Doxygen, see <link linkend="appendix.porting.doc">Documentation
  37      Hacking</link> in the appendix for full details.
  38    </para>
  39
  40    <para>
  41    Finally, a few system-specific requirements:
  42    </para>
  43
  44    <variablelist>
  45       <varlistentry>
  46         <term>linux</term>
  47
  48         <listitem>
  49         <para>
  50           The 'gnu' locale model makes use of <function>iconv</function>
  51           for character set conversions. The relevant functions are provided
  52           by Glibc and so are always available, however they can also be
  53           provided by the separate GNU libiconv library. If GNU libiconv is
  54           found when GCC is built (e.g., because its headers are installed
  55           in <filename class="directory">/usr/local/include</filename>)
  56           then the <filename>libstdc++.so.6</filename> library will have a
  57           run-time dependency on <filename>libiconv.so.2</filename>.
  58           If you do not want that run-time dependency then you should do
  59           one of the following:
  60         </para>
  61         <itemizedlist>
  62           <listitem>
  63             <para>
  64               Uninstall the libiconv headers before building GCC.
  65               Glibc already provides <function>iconv</function> so you should
  66               not need libiconv anyway.
  67             </para>
  68           </listitem>
  69           <listitem>
  70             <para>
  71             <link xmlns:xlink="http://www.w3.org/1999/xlink"
  72               xlink:href="https://www.gnu.org/software/libiconv/#downloading">
  73             Download</link> the libiconv sources and extract them into the
  74             top level of the GCC source tree, e.g.,
  75             </para>
  76 <programlisting>
  77 wget https://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.16.tar.gz
  78 tar xf libiconv-1.16.tar.gz
  79 ln -s libiconv-1.16 libiconv
  80 </programlisting>
  81             <para>
  82               This will build libiconv as part of building GCC and link to
  83               it statically, so there is no <filename>libiconv.so.2</filename>
  84               dependency.
  85             </para>
  86           </listitem>
  87           <listitem>
  88             <para>
  89               Configure GCC with <option>--with-libiconv-type=static</option>.
  90               This requires the static <filename>libiconv.a</filename> library,
  91               which is not installed by default. You might need to reinstall
  92               libiconv using the <option>--enable-static</option> configure
  93               option to get the static library.
  94             </para>
  95           </listitem>
  96         </itemizedlist>
  97         </listitem>
  98
  99         <listitem>
 100         <para>
 101           If GCC 3.1.0 or later on is being used on GNU/Linux, an attempt
 102           will be made to use "C" library functionality necessary for
 103           C++ named locale support, e.g. the <function>newlocale</function>
 104           and <function>uselocale</function> functions.
 105           For GCC 4.6.0 and later,
 106           this means that glibc 2.3 or later is required.
 107         </para>
 108
 109         <para>
 110           If the 'gnu' locale model is being used, the following
 111           locales are used and tested in the libstdc++ testsuites.
 112           The first column is the name of the locale, the second is
 113           the character set it is expected to use.
 114         </para>
 115 <programlisting>
 116 de_DE               ISO-8859-1
 117 de_DE@euro          ISO-8859-15
 118 en_GB               ISO-8859-1
 119 en_HK               ISO-8859-1
 120 en_PH               ISO-8859-1
 121 en_US               ISO-8859-1
 122 en_US.ISO-8859-1    ISO-8859-1
 123 en_US.ISO-8859-15   ISO-8859-15
 124 en_US.UTF-8         UTF-8
 125 es_ES               ISO-8859-1
 126 es_MX               ISO-8859-1
 127 fr_FR               ISO-8859-1
 128 fr_FR@euro          ISO-8859-15
 129 is_IS               UTF-8
 130 it_IT               ISO-8859-1
 131 ja_JP.eucjp         EUC-JP
 132 ru_RU.ISO-8859-5    ISO-8859-5
 133 ru_RU.UTF-8         UTF-8
 134 se_NO.UTF-8         UTF-8
 135 ta_IN               UTF-8
 136 zh_TW               BIG5
 137 </programlisting>
 138
 139       <para>Failure to have installed the underlying "C" library
 140       locale information for any of the above regions means that
 141       the corresponding C++ named locale will not work:  because of
 142       this, the libstdc++ testsuite will skip named locale tests
 143       which need missing information.  If this isn't an issue, don't
 144       worry about it.  If a named locale is needed, the underlying
 145       locale information must be installed.  Note that rebuilding
 146       libstdc++ after "C" locales are installed is not necessary.
 147       </para>
 148
 149       <para>
 150         To install support for locales, do only one of the following:
 151       </para>
 152
 153       <itemizedlist>
 154         <listitem>
 155           <para>install all locales, e.g., run
 156             <code> dnf install glibc-all-langpacks </code>
 157             for Fedora and related distributions.
 158           </para>
 159         </listitem>
 160         <listitem>
 161           <para>install just the necessary locales</para>
 162           <itemizedlist>
 163             <listitem>
 164               <para>with Debian GNU/Linux:</para>
 165               <para> Add the above list, as shown, to the file
 166               <code>/etc/locale.gen</code> </para>
 167               <para> run <code>/usr/sbin/locale-gen</code> </para>
 168             </listitem>
 169             <listitem>
 170               <para>on most Unix-like operating systems:</para>
 171               <para><code> localedef -i de_DE -f ISO-8859-1 de_DE </code></para>
 172               <para>(repeat for each entry in the above list) </para>
 173             </listitem>
 174             <listitem>
 175             <para>
 176                Instructions for other operating systems solicited.
 177             </para>
 178             </listitem>
 179           </itemizedlist>
 180         </listitem>
 181       </itemizedlist>
 182       </listitem>
 183
 184       <listitem>
 185         Some tests for the <code>std::messages</code> facet require a
 186         message catalog created by the <command>msgfmt</command> utility.
 187         That is usually installed as part of the GNU gettext library.
 188         If <command>msgfmt</command> is not available, some tests under
 189         the <filename class="directory">22_locale/messages</filename>
 190         directory will fail.
 191       </listitem>
 192
 193       </varlistentry>
 194    </variablelist>
 195
 196 </section>