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