install.texi

GCC

file corrections made by the @code{fixincludes} script.

Indications are that people who use this option use it based on mistaken
ideas of what it is for.  People use it as if it specified where to
install part of GCC.  Perhaps they make this assumption because
installing GCC creates the directory.

@item --enable-shared[=@var{package}[,@dots{}]]
Build shared versions of libraries, if shared libraries are supported on
the target platform.  Unlike GCC 2.95.x and earlier, shared libraries
are enabled by default on all platforms that support shared libraries.

If a list of packages is given as an argument, build shared libraries
only for the listed packages.  For other packages, only static libraries
will be built.  Package names currently recognized in the GCC tree are
@samp{libgcc} (also known as @samp{gcc}), @samp{libstdc++} (not
@samp{libstdc++-v3}), @samp{libffi}, @samp{zlib}, @samp{boehm-gc} and
@samp{libjava}.  Note that @samp{libobjc} does not recognize itself by
any name, so, if you list package names in @option{--enable-shared},
you'll only get static Objective C libraries.  @samp{libf2c} and
@samp{libiberty} do not support shared libraries at all.

Use @option{--disable-shared} to build only static libraries.  Note that
@option{--disable-shared} does not accept a list of package names as
argument, only @option{--enable-shared} does.

@item @anchor{with-gnu-as}--with-gnu-as
Specify that the compiler should assume that the
assembler it finds is the GNU assembler. However, this does not modify
the rules to find an assembler and will result in confusion if found
assembler is not actually the GNU assembler.  If you have more than one
assembler installed on your system, you may want to use this option in
connection with @option{--with-as=@file{/path/to/gas}}.

@item --with-as=@file{/path/to/as}
Specify that the
compiler should use the assembler pointed to by @var{pathname}, rather
than the one found by the standard rules to find an assembler, which
are:
@itemize @bullet
@item
Check the
@file{@var{exec_prefix}/lib/gcc-lib/@var{target}/@var{version}}
directory, where @var{exec_prefix} defaults to @var{prefix} which
defaults to @file{/usr/local} unless overridden by the
@option{--prefix=/pathname} switch described above. @var{target} is the
target system triple, such as @var{sparc-sun-solaris2.7}, and
@var{version} denotes the GCC version, such as 2.95.2.
@item
Check operating system specific directories (e.g. @file{/usr/ccs/bin} on
Sun Solaris).
@end itemize
Note that these rules do not check for the value of @env{PATH}. You may
want to use @option{--with-as} if no assembler is installed in the
directories listed above, or if you have multiple assemblers installed
and want to choose one that is not found by the above rules.

@item @anchor{with-gnu-ld}--with-gnu-ld
Same as @uref{#with-gnu-as,,@option{--with-gnu-as}}
but for linker.


@item --with-ld=@file{/path/to/ld}
Same as
@option{--with-as}, but for the linker.

@item --with-stabs
Specify that stabs debugging
information should be used instead of whatever format the host normally
uses.  Normally GCC uses the same debug format as the host system.

@item --enable-multilib
Specify that multiple target
libraries should be built to support different target variants, calling
conventions, etc.  This is the default.

@item --enable-threads
Specify that the target
supports threads.  This affects the Objective-C compiler and runtime
library, and exception handling for other languages like C++ and Java.
On some systems, this is the default.

@item --enable-threads=@var{lib}
Specify that
@var{lib} is the thread support library.  This affects the Objective-C
compiler and runtime library, and exception handling for other languages
like C++ and Java.  The possibilities for @var{lib} are:

@table @code
@item aix
AIX thread support.
@item dce
DCE thread support.
@item decosf1
DEC OSF/1 thread support.
@item irix
SGI IRIX thread support.
@item mach
Generic MACH thread support, known to work on NEXTSTEP.
@item os2
IBM OS/2 thread support.
@item posix
Generic POSIX thread support.
@item pthreads
Same as @samp{posix}.
@item single
Disable thread support, should work for all platforms.
@item solaris
SUN Solaris thread support.
@item vxworks
VxWorks thread support.
@item win32
Microsoft Win32 API thread support.
@end table

@item --with-cpu=@var{cpu}
Specify which cpu variant the
compiler should generate code for by default.  This is currently
only supported on the some ports, specifically arm, powerpc, and
SPARC. If configure does not recognize the model name (e.g. arm700,
603e, or ultrasparc) you provide, please check the configure script
for a complete list of supported models.

@item --enable-target-optspace
Specify that target
libraries should be optimized for code space instead of code speed.
This is the default for the m32r platform.

@item --disable-cpp
Specify that a user visible @command{cpp} program should not be installed.

@item --with-cpp-install-dir=@var{dirname}
Specify that the user visible @command{cpp} program should be installed
in @file{@var{prefix}/@var{dirname}/cpp}, in addition to @var{bindir}.

@item --enable-maintainer-mode
The build rules that
regenerate the GCC master message catalog @file{gcc.pot} are normally
disabled. This is because it can only be rebuilt if the complete source
tree is present. If you have changed the sources and want to rebuild the
catalog, configuring with @option{--enable-maintainer-mode} will enable
this. Note that you need a recent version of the @code{gettext} tools
to do so.

@item --enable-version-specific-runtime-libs
Specify
that runtime libraries should be installed in the compiler specific
subdirectory (@file{@var{libsubdir}}) rather than the usual places.  In
addition, libstdc++'s include files will be installed in
@file{@var{libsubdir}/include/g++} unless you overruled it by using
@option{--with-gxx-include-dir=@var{dirname}}.  Using this option is
particularly useful if you intend to use several versions of GCC in
parallel. This is currently supported by @samp{libf2c} and
@samp{libstdc++}.

@item --enable-languages=@var{lang1},@var{lang2},@dots{}
Specify that only a particular subset of compilers and
their runtime libraries should be built. For a list of valid values for
@var{langN} you can issue the following command in the
@file{gcc} directory of your GCC source tree:@* @samp{grep language=
*/config-lang.in}@* Currently, you can use any of the following:
@code{c++}, @code{f77}, @code{java} and @code{objc}.
@code{CHILL} is not currently maintained, and will almost
certainly fail to compile.  Note that this switch does not work with
EGCS 1.1.2 or older versions of egcs.  It is supported in GCC 2.95
and newer versions.@*
If you do not pass this flag, all languages available in the @file{gcc}
sub-tree will be configured.  Re-defining @code{LANGUAGES} when calling
@samp{make bootstrap} @strong{does not} work anymore, as those
language sub-directories might not have been configured!

@item --disable-libgcj
Specify that the run-time libraries
used by GCJ should not be built.  This is useful in case you intend
to use GCJ with some other run-time, or you're going to install it
separately, or it just happens not to build on your particular
machine.  In general, if the Java front-end is enabled, the GCJ
libraries will be enabled too, unless they're known to not work on
the target platform.  If GCJ is enabled but libgcj isn't built, you
may need to port it; in this case, before modifying the top-level
@file{configure.in} so that libgcj is enabled by default on this platform,
you may use @option{--enable-libgcj} to override the default.

@item --with-dwarf2
Specify that the compiler should
use DWARF2 debugging information as the default.

@item --enable-win32-registry
@itemx --enable-win32-registry=@var{KEY}
@itemx --disable-win32-registry
The @option{--enable-win32-registry} option enables Windows-hosted GCC
to look up installations paths in the registry using the following key:

@smallexample
@code{HKEY_LOCAL_MACHINE\SOFTWARE\Free Software Foundation\@var{KEY}}
@end smallexample

@var{KEY} defaults to GCC version number, and can be overridden by the
@option{--enable-win32-registry=@var{KEY}} option. Vendors and distributors
who use custom installers are encouraged to provide a different key,
perhaps one comprised of vendor name and GCC version number, to
avoid conflict with existing installations. This feature is enabled
by default, and can be disabled by @option{--disable-win32-registry}
option.  This option has no effect on the other hosts.

@item --nfp
Specify that the machine does not have a floating point unit.  This
option only applies to @samp{m68k-sun-sunos@var{n}} and
@samp{m68k-isi-bsd}.  On any other system, @option{--nfp} has no effect.

@item --enable-checking
@itemx --enable-checking=@var{list}
When you specify this option, the compiler is built to perform checking
of tree node types when referencing fields of that node, and some other
internal consistency checks.  This does not change the generated code,
but adds error checking within the compiler.  This will slow down the
compiler and may only work properly if you are building the compiler
with GNU C.  This is on by default when building from CVS or snapshots,
but off for releases.  More control over the checks may be had by
specifying @var{list}; the categories of checks available are
@samp{misc}, @samp{tree}, @samp{gc}, @samp{rtl} and @samp{gcac}.  The
default when @var{list} is not specified is @samp{misc,tree,gc}; the
checks @samp{rtl} and @samp{gcac} are very expensive.

@item --enable-nls
@itemx --disable-nls
The @option{--enable-nls} option enables Native Language Support (NLS),
which lets GCC output diagnostics in languages other than American
English. Native Language Support is enabled by default if not doing a
canadian cross build. The @option{--disable-nls} option disables NLS.

@item --with-included-gettext
If NLS is enabled, the @option{--with-included-gettext} option causes the build
procedure to prefer its copy of GNU @code{gettext}.

@item --with-catgets
If NLS is enabled, and if the host lacks @code{gettext} but has the
inferior @code{catgets} interface, the GCC build procedure normally
ignores @code{catgets} and instead uses GCC's copy of the GNU
@code{gettext} library.  The @option{--with-catgets} option causes the
build procedure to use the host's @code{catgets} in this situation.
@end table

Some options which only apply to building cross compilers:
@table @code
@item --with-headers=@var{dir}
Specifies a directory
which has target include files.
@emph{This options is required} when building a cross
compiler, if @file{@var{prefix}/@var{target}/sys-include} doesn't pre-exist.
These include files will be copied into the @file{gcc} install directory.
Fixincludes will be run on these files to make them compatible with
@command{gcc}.
@item --with-libs=``@var{dir1} @var{dir2} @dots{} @var{dirN}''
Specifies a list of directories which contain the target runtime
libraries.  These libraries will be copied into the @file{gcc} install
directory.
@item --with-newlib
Specifies that ``newlib'' is
being used as the target C library.  This causes @code{__eprintf} to be
omitted from libgcc.a on the assumption that it will be provided by
newlib.
@end table
 
Note that each @option{--enable} option has a corresponding
@option{--disable} option and that each @option{--with} option has a
corresponding @option{--without} option.

@html
<hr>
<p>
@end html
@ifhtml
@uref{./index.html,,Return to the GCC Installation page}
@end ifhtml
@end ifset

@c ***Building****************************************************************
@ifnothtml
@comment node-name,     next,          previous, up
@node    Building, Testing, Configuration, Installing GCC
@end ifnothtml
@ifset buildhtml
@html
<h1 align="center">Installing GCC: Building</h1>
@end html
@ifnothtml
@chapter Building
@end ifnothtml
@cindex Installing GCC: Building

Now that GCC is configured, you are ready to build the compiler and
runtime libraries.

We @strong{highly} recommend that GCC be built using GNU make;
other versions may work, then again they might not.

(For example, many broken versions of make will fail if you use the
recommended setup where @var{objdir} is different from @var{srcdir}.
Other broken versions may recompile parts of the compiler when
installing the compiler.)

Some commands executed when making the compiler may fail (return a
non-zero status) and be ignored by @code{make}.  These failures, which
are often due to files that were not found, are expected, and can safely
be ignored.

It is normal to have compiler warnings when compiling certain files.
Unless you are a GCC developer, you can generally ignore these warnings
unless they cause compilation to fail.

On certain old systems, defining certain environment variables such as
@env{CC} can interfere with the functioning of @command{make}.

If you encounter seemingly strange errors when trying to build the
compiler in a directory other than the source directory, it could be
because you have previously configured the compiler in the source
directory.  Make sure you have done all the necessary preparations.

If you build GCC on a BSD system using a directory stored in an old System
V file system, problems may occur in running @code{fixincludes} if the
System V file system doesn't support symbolic links.  These problems
result in a failure to fix the declaration of @code{size_t} in
@file{sys/types.h}.  If you find that @code{size_t} is a signed type and
that type mismatches occur, this could be the cause.

The solution is not to use such a directory for building GCC.

When building from CVS or snapshots, or if you modify parser sources,
you need the Bison parser generator installed.  Any version 1.25 or
later should work; older versions may also work.  If you do not modify
parser sources, releases contain the Bison-generated files and you do
not need Bison installed to build them.

When building from CVS or snapshots, or if you modify Texinfo
documentation, you need version 4.0 or later of Texinfo installed if you
want Info documentation to be regenerated.  Releases contain Info
documentation pre-built for the unmodified documentation in the release.

@section Building a native compiler

For a native build issue the command @samp{make bootstrap}.  This 
will build the entire GCC system, which includes the following steps:

@itemize @bullet
@item
Build host tools necessary to build the compiler such as texinfo, bison,
gperf.

@item
Build target tools for use by the compiler such as binutils (bfd,
binutils, gas, gprof, ld, and opcodes)@*
if they have been individually linked 
or moved into the top level GCC source tree before configuring.

@item
Perform a 3-stage bootstrap of the compiler.

@item
Perform a comparison test of the stage2 and stage3 compilers.

@item
Build runtime libraries using the stage3 compiler from the previous step.
 
@end itemize

If you are short on disk space you might consider @samp{make
bootstrap-lean} instead.  This is identical to @samp{make
bootstrap} except that object files from the stage1 and
stage2 of the 3-stage bootstrap of the compiler are deleted as
soon as they are no longer needed.


If you want to save additional space during the bootstrap and in
the final installation as well, you can build the compiler binaries