
		CrossGCC Frequently Asked Questions
		===================================

Version: 0.8
Last Updated: 970317
Maintainer: dje@cygnus.com
Location: ftp://ftp.cygnus.com/pub/embedded/crossgcc/FAQ

`crossgcc' is the name of a mailing list for discussing issues regarding
using GCC (plus the various ancilliary pieces) as a cross-compiler.

Subscription requests should be sent to "crossgcc-request@cygnus.com"
with a body of 1 line containing "subscribe crossgcc <your-email-address>"
and nothing else (and no <>'s around your email address).
To unsubscribe, send a message to  "crossgcc-request@cygnus.com"
with a body of 1 line containing "unsubscribe crossgcc <your-email-address>"
and nothing else (and no <>'s around your email address).
The email address you use to unsubscribe *must* be identical, character for
character, to one used to subscribe, and case is important too.

This list is run by the "majordomo" software.

This FAQ is unfinished (in the sense that there are some obvious sections
it needs, some included below).  Please send contributions to dje@cygnus.com.

Table of Contents
-----------------

1.  List of the pieces needed and where to find them

2.  Patches

    2.1 Cygnus patches
    2.2 Patch for binutils-2.6 GAS bug "Case value 3 unexpected at line 1557"

3.  How to configure, build, and install GCC as a cross-compiler

    3.1 Unix and related systems
    3.2 One pass installation of GCC+Binutils
    3.3 Can I build in a directory different from the source tree?
    3.4 Can I use a non-GNU make?
    3.5 Cygnus releases
    3.5.1 Where are the info files?
    3.5.2 How do I build a Cygnus release?
    3.6 Win32 systems
    3.7 MSDOS systems
    3.7.1 How do I build a cross-compiler with DJGPP?
    3.8 Canadian Crosses
        (or, Building a DOS hosted cross compiler without using DOS)
    3.8.1 What is a Canadian Cross?
    3.8.2 How do I build an MSDOS hosted cross compiler without using MSDOS?
    3.9 Disk space requirements

4.  Frequently Encountered Problems

    4.1 installation problem, cannot exec `cpp': No such file or directory
    4.2 64 bit host cross 32 bit target
    4.3 Assembler errors while building GCC's libgcc.a
    4.4 Unresolved symbols during linking
    4.5 Where are open, read, write, close, etc. ?
    4.6 How do I pass options from GCC to GAS or GLD?
    4.7 How do I write an interrupt handler in C?
    4.8 How do I write assembler code that works with m68k-aout's leading
        '_' and m68k-coff's lack of leading '_'?

5.  Library Support

    5.1 What is libgcc.a?
    5.2 How do I force GCC to emit inline code for memcpy?
    5.3 Why would I choose glibc over newlib (or vice versa)?
    5.4 What if I need software floating point support?
    5.5 Why are several copies of newlib built?
    5.5.1 Is there any way to build only the libraries I need?

6.  Using GDB for remote debugging

7.  S Records, etc.

    6.1 What are S Records?
    6.1 How do I use objcopy to generate S Records?
    6.2 How do I use the linker to generate S Records?

8.  Target specific info

    8.1 What embedded targets are supported?

9.  Operating systems for embedded systems

    9.1 RTEMS

10. How to get help

    10.1 General questions
    10.2 Online docs
    10.3 Bug reporting
    10.4 Other mailing lists, web sites, newsgroups, etc.

11. Glossary

12. Contributors

1. List of the pieces needed and where to find them

For a complete toolchain you need a compiler (GCC), assembler (GAS),
linker (GLD), various utilities (Binutils), debugger (GDB), and a library
(GLIBC or NEWLIB).  For c++ programming you'll also want libg++.

The master repository of GNU software is prep.ai.mit.edu:/pub/gnu.
It is mirrored all over the world so please try to use a site closer to
you to avoid overloading prep.  The list of sites can be obtained with
"finger fsf@prep.ai.mit.edu".

Compiler: GCC 2.7.2.1, file gcc-2.7.2.1.tar.gz

	gcc-2.7.2.2 may also be used, it's difference over 2.7.2.1 is
	for linux native compilers, which aren't a concern here.

Assembler: GAS 2.7, file binutils-2.7.tar.gz

Linker: GLD 2.7, file binutils-2.7.tar.gz

Utilities: Binutils 2.7, file binutils-2.7.tar.gz

Debugger: GDB 4.16, file gdb-4.16.tar.gz

Library: There are currently two choices for a library, the GNU libc (Glibc)
and a library put together by Cygnus (Newlib).
	GLIBC 2.0.1, file glibc-2.0.1.tar.gz
	Newlib 1.7.1, file newlib-1.7.1.tar.gz in directory
		ftp.cygnus.com:/pub/newlib

2. Patches

This section is intended to document patches that are available from
various sources.

2.1 Cygnus patches

crossgcc-gcc-2.7.2.1.patch

	This patch adds these things.
	a. Delete building of objc-runtime.
	   This library requires the C library header files which usually
	   aren't available when the user is first building the cross
	   compiler.  They *could* be, but this is a frequent source of
	   trouble to users so this patch avoids the trouble.
	b. float.h
	   GCC's Makefile expects to be able to run `enquire' to compute
	   float.h.  When building a cross compiler this can require manual
	   intervention in the build process (and hence a source of confusion
	   for users) and on some embedded systems it may be impossible to
	   run enquire.  This patch provides some prebuilt versions of
	   float.h that targets can use.
	   ??? The support is incomplete.  For example, 96 bit and 128 bit
	   floating point support is missing.
	c. Define inhibit_libc in LIBGCC2_FLAGS if cross compiler.
	   Various routines in libgcc2.c require headers like stdio.h which
	   typically aren't available yet (see point a.).
	   Defining inhibit_libc causes __eprintf to be left out of libgcc.a;
	   this is ok because it is only used by assert.h and the C library
	   will be providing its own assert.h.
	   It also causes profiling support to be left out of libgcc.a,
	   these routines also require C library headers like stdio.h.
	d. Provide support for i386-go32 as a target.
	   This is needed for example in a Canadian Cross where one is
	   building a DOS hosted cross compiler from a Unix system.
	e. Provide ppc-asm.h.

The patch is available in ftp.cygnus.com:/pub/embedded/crossgcc.
To apply the patch:

cd gcc-2.7.2.1
patch <../crossgcc-gcc-2.7.2.1.patch

crossgcc-gcc-2.7.2.2.patch is also available it is identical to
crossgcc-gcc-2.7.2.1.patch except for a few changes necessary to make
it apply properly.

2.2 Patch for binutils-2.6 GAS bug "Case value 3 unexpected at line 1557"

Binutils-2.6 has a bug in the i386 port of GAS that can cause this error.

/var/tmp/cca002vk.s: Assembler messages:
/var/tmp/cca002vk.s:12: Fatal error: Case value 3 unexpected at line 1557 of file "obj-format.c"

This bug is present in all i386 ports.  The patch is in
ftp://ftp.cygnus.com/pub/embedded/crossgcc/binutils-2.6-obj-coff.patch

This patch is not necessary for binutils-2.7 or later.

3. How to configure, build, and install GCC as a cross-compiler

3.1 Unix Systems

Notes:
1) The author has more familiarity with Newlib than Glibc so Newlib
   will be used in all examples below.
2) GAS and GLD are now distributed in the "binutils" distribution,
   so all further references to GAS and GLD in this section will use
   Binutils instead.
3) If you have a "make" that understands VPATH (like GNU make), it is
   highly recommended that you build the pieces in a different directory
   from the sources.  The examples below will assume this.

The pieces have to be built and installed in a particular order.
Why?  Clearly the cross-compiler is needed to build the libraries,
so GCC must be built before Newlib.  Also, GCC has its own library
(called libgcc) so Binutils must be built before GCC.

Here is the recommended order:

1) Binutils
2) GCC
3) Newlib
4) GDB

Suppose
- you've unpacked all the sources into /home/foo,
- you want to build a sparc-solaris2 hosted m68k-coff cross-compiler,
- the cross-compiler is to be installed in /bar.
The build procedure would then look like this.

cd /home/foo
host=sparc-sun-solaris2
target=m68k-coff
prefix=/bar
i=$prefix/bin

mkdir build-binutils build-gcc build-newlib build-gdb

# Configure, build and install binutils
cd build-binutils
../binutils-2.7/configure --host=$host --target=$target --prefix=$prefix -v
make all install

# Configure, build and install gcc
cd ../build-gcc
../gcc-2.7.2.1/configure --host=$host --target=$target --prefix=$prefix -v
make all install

# Configure, build and install newlib
cd ../build-newlib
../newlib-1.7.1/configure --host=$host --target=$target --prefix=$prefix -v
# The settings for FOO_FOR_TARGET aren't necessary if you put $prefix/bin
# in your path before running this.
make all install \
	CC_FOR_TARGET=$i/bin/${target}-gcc \
	AS_FOR_TARGET=$i/bin/${target}-as \
	LD_FOR_TARGET=$i/bin/${target}-ld \
	AR_FOR_TARGET=$b/binutils/${target}-ar \
	RANLIB_FOR_TARGET=$b/binutils/${target}-ranlib

# Configure, build and install gdb
cd ../build-gdb
../gdb-4.16/configure --host=$host --target=$target --prefix=$prefix -v
make all install

3.2 One Pass Installation

Is there an easier way?  Yes!
If you study the top-level Makefile that comes with binutils-2.7,
newlib-1.7.1, or gdb-4.16, you'll see that they're all quite similar
(not surprising since they're essentially the same file).

You'll also discover that it is capable of building and installing the
entire toolchain in one pass.  The catch is that is assumes a directory
layout different than what would normally appear when you unpack the
sources.

You will need to apply the Cygnus crossgcc-gcc-2.7.2.1.patch.

What we now need to do is turn this directory layout

./binutils-2.7/
               bfd/
               binutils/
               config/
               gas/
               include/
               ld/
               libiberty/
               opcodes/
               texinfo/
./gcc-2.7.2.1/
./newlib-1.7.1/
               config/
               libgloss/
               newlib/
               texinfo/

into

./src/
      bfd/
      binutils/
      config/
      gas/
      gcc/
      include/
      ld/
      libgloss/
      libiberty/
      newlib/
      opcodes/
      texinfo/

Where's GDB?  GDB is left out because it shares sources with Binutils
(e.g. bfd, include, libiberty, and opcodes).  One can't "mix and match" them,
they each need there own copies (since they were tested and released with
their own copies).  GDB can be built separately afterwards.  One might well
ask what's the point of this pseudo one-pass installation and that would be
a good question.  It simplifies the installation a little, and in particular
the "Canadian Cross" installation (see below).

Binutils and Newlib share `config' and `texinfo' directories; we can use
Binutils' copies.

A script exists to reorganize the above source tree using symlinks.
It assumes:
- you're using a version of make that understands VPATH (e.g. GNU make)
- ./binutils-2.7 exists
- ./gcc-2.7.2.1 exists
- ./newlib-1.7.1 exists
- ./src does not exist

The script is one-tree-1.3.sh from ftp.cygnus.com:/pub/embedded/crossgcc.
It will create a subdirectory called `src'.

After running the script, do this:

mkdir build
cd build
../src/configure --host=$host --target=$target --prefix=$prefix -v
make all install

mkdir ../build-gdb
cd ../build-gdb
../gdb-4.16/configure --host=$host --target=$target --prefix=$prefix -v
make all install

3.3 Can I build in a directory different from the source tree?

Yes.

However, it requires a version of make that understands VPATH.
SunOS make may or may not be sufficient: it's VPATH support has problems
which require extra effort to support and developers don't always adhere
to the restrictions.  If you don't use GNU make you're on your own
as far as getting the build to work.

3.4 Can I use a non-GNU make?

Yes.

However, there are a few things to be wary of:

- you must build in the source tree

- testing generally isn't done with non-GNU makes so one is more likely to
  run into build problems - these problems can be fixed of course but it may
  require effort on your part

3.5 Cygnus Releases

3.5.1 Where are the info files?

Cygnus releases differ from FSF releases in that files that are not really
source files but are built from other files (like yacc files and texinfo
files) are not included.  Instead, they are built with the rest of the
toolchain.

3.5.2 How do I build a Cygnus release?

Cygnus releases are essentially the "one-pass installation" tree, except
that a lot more tools are included (e.g. byacc, flex, expect, gdb, make, tcl,
texinfo).

To build a toolchain from a Cygnus release, you should consult the
documentation that came with it (there may be last minute release notes,
or this FAQ may be out of date, etc.).  But for those who happen to come
upon a Cygnus release, here is a quick introduction.

Suppose you happen upon a Cygnus release and want to build a
sparc-sun-solaris2 cross h8300-hms compiler.  Do this:

src=/path/to/source/tree
rel=/path/to/install/tree
host=sparc-sun-solaris2
target=h8300-hms
mkdir build
cd build
$src/configure --host=$host --target=$target --prefix=$rel -v
make all info install install-info
PATH=$PATH:$rel/bin ; export PATH

You can also run dejagnu on the build tree at this point with

make -k check

The gcc and g++ execute tests won't do much in this particular example
unless dejagnu has been configured to use the simulator or target board
for the execute tests.

3.6 Win32 hosted cross-compilers

There is work in progress that will let the GNU tools be used as a native
compiler in the win32 environment and also as a cross-compiler (either win32
hosted or win32 targeted).  Join the gnu-win32@cygnus.com mailing list if
you wish to help out.  The release is kept in
ftp://ftp.cygnus.com/pub/gnu-win32.

The configuration for this project is i386-cygwin32.

Subscription requests should be sent to "gnu-win32-request@cygnus.com"
with a body of 1 line containing "subscribe gnu-win32 <your-email-address>"
and nothing else (and no <>'s around your email address).

3.7 MSDOS hosted cross-compilers

The primary MSDOS port is version 1 of `djgpp', a port of the GNU tools to
MSDOS by DJ Delorie, using `go32', a 32 bit extender.  See the djgpp FAQ for
more details (http://www.delorie.com/djgpp/faq/).

3.7.1 How do I build a cross-compiler with DJGPP?

The procedure is basically this.

* Use gunzip to decompress the various archives.

* Use djtarx to untar them and resolve 8.3 conflicts

* Run "configure" in all the right places to configure for a native
  compiler.

* Manually (read the INSTALL file) copy the target-specific files around
  to reconfigure the system for the given target.  Edit the Makefiles
  as appropriate to include the target snippets.

* Run make.

3.8 Canadian Crosses

3.8.1 What is a Canadian Cross?

One cool thing about the GNU tools is that they support building a cross
compiler for one host on another host (i.e. building a cross-compiler with
a cross-compiler).  This is called a "Canadian Cross" because at the time
a name was needed, Canada had three national parties.  "Three" is important
because there are three different systems involved: the build machine, the
host machine, and the target machine.  I think Canada has six national
parties now so the name is a bit dated, but who cares.  This allows, for
example, one to build an MSDOS hosted cross-compiler on a Unix box.  

3.8.2 How do I build an MSDOS hosted cross compiler without using MSDOS?

Suppose one wanted to build an MSDOS cross m68k-coff cross
compiler on a sparc-sunos4 machine.  The procedure is as follows.
Note that it is quite lengthy.  That's because four compilers are involved
(three to build the one we want).

Why four?  Remember, we're building the tools completely on a Unix box,
therefore all the programs that run during the build process must obviously
run on the Unix box.  We can't skip over to an MSDOS machine, run something
there, and come back - the entire toolchain is built from scratch on the
Unix box.

The first compiler that is needed is a sunos4 cross m68k-coff compiler
to build the m68k-coff libraries.  But in order to build that we need
a sunos4 native compiler.  That's two.  We also need a sunos4 cross
i386-go32 compiler to build the programs that run on MSDOS (go32 is the
name of a 32 bit extender (*) written by DJ Delorie that all the MSDOS
tools will use).  Finally, we need an i386-go32 cross m68k-coff compiler:
our final goal.  Four compilers.  However, the process is quite
straightforward once you understand all the pieces that are needed.

(*) The 32 bit extender is no longer required with recent versions of go32.
However, newlib has not been updated.

Assume the source tree has been created with the "one-tree" script.
The following is the list of steps, written so that it can be copied
into a shell script and run.

#!/bin/sh
# This script is build-3way.sh from crossgcc FAQ-0.8.
# Before using this script it is a good idea to check with the most recent
# version of the FAQ to see if any changes have been made.  The FAQ can be
# obtained from ftp://ftp.cygnus.com/pub/embedded/crossgcc/FAQ.
#
# This patch assumes:
# - the source tree contains binutils, gcc, and newlib build with the
#   one-tree script
# - that crossgcc-gcc-2.x.y.patch has been applied
#
# Note: This script provides support for cygwin32 hosts (the configuration
# of the gnu-win32 project), but current FSF releases of GCC,Binutils do not
# support cygwin32.  The support is present in case you pick up a copy of
# the cygwin32 source tree.
#
# Syntax: sh build-3way.sh [install]
#
# The default is to configure and build, but not install.
#
# The recommended way to use this script is to modify the variables
# build,host,target,src,rel,relexec as necessary, then run:
#
# build-3way.sh
# build-3way.sh install
#
# The process is rather involved as there are a lot of steps.
# On the other hand, it is really rather straightforward.
# The goal is to build a $host cross $target toolchain.  Some hosts aren't
# well suited to program development (eg: msdos) and other hosts may not have
# complete GNU support yet.  Both of these cases are ideallyhandled by a
# script like this where we build everything in a more familiar and
# comfortable environment (eg: unix).
#
# The toolchain we are building is composed of basically two pieces:
#
# 1) programs that run in the host environment.
#    These include gcc, cpp, cc1, as, ld, objdump, etc.  These critters
#    are built with a $build cross $host cross-compiler.
#
# 2) libraries of functions that run in the target environment.
#    These include libgcc.a, libc.a, libm.a, etc.  These critters are
#    built with a $build cross $target cross-compiler.
#
# We end up building 3 complete toolchains: $build cross $host,
# $build cross $target, and ultimately $host cross $target.
# Remember, the only environment in which we can run programs is $build:
# that is the reason for the complexity.
#
# The cool thing is that this can be done at all!

set -e

here=`pwd`

action=$1

build=sparc-sun-solaris2
host=i386-go32
target=m68k-coff
src=$here/src
rel=/tmp/test
relexec=$rel/H-${host}

# Build directory for the $build cross $host toolchain.
b2h=$here/b-${build}-x-${host}
# Build directory for the $build cross $target toolchain.
b2t=$here/b-${build}-x-${target}
# Build directory for the $host cross $target toolchain.
h2t=$here/b-${host}-x-${target}

######################################################################
#
# The first step is to build a $build cross $host cross-compiler.

if [ ! -f $b2h/configure.done ] ; then
    [ -d $b2h ] || mkdir $b2h
    (cd $b2h ; CC=gcc $src/configure --host=${build} --target=${host} --prefix=/tmp/junk -v)
    touch $b2h/configure.done
fi
# For cygwin32 so mount,umount get built.
(
	cd $b2h/gcc
	rm -f crt0.o libc.a libg.a libm.a libcygwin.a libkernel32.a
	ln -s ../${host}/newlib/crt0.o .
	ln -s ../${host}/newlib/libc.a .
	ln -s ../${host}/newlib/libg.a .
	ln -s ../${host}/newlib/libm.a .
	ln -s ../${host}/winsup/libcygwin.a .
	ln -s ../${host}/winsup/libkernel32.a .
)
(cd $b2h ; make -w all-target-newlib all-target-winsup CC=gcc)

######################################################################
#
# Now build a $build cross $target toolchain.
# The value for --prefix we give here is /tmp/junk as we don't intend
# to install this toolchain.

if [ ! -f $b2t/configure.done ] ; then
    [ -d $b2t ] || mkdir $b2t
    (cd $b2t ; CC=gcc $src/configure --host=${build} --target=${target} --prefix=/tmp/junk -v)
    touch $b2t/configure.done
fi
#(cd $b2t ; make -w all-gcc all-target-newlib CC=gcc CFLAGS=-g)
(cd $b2t ; make -w all-gcc CC=gcc CFLAGS=-g)

######################################################################
#
# Now that we've built the tools that we need, we can finally build
# our $host cross $target toolchain.

# Unfortunately, autoconf doesn't like "path prefix unused" messages, so
# we can't use -B../newlib/.  This works around that.  The alternative
# is to install the $build cross $host toolchain and use that.

(
	cd $b2h/gcc
	rm -f crt0.o libc.a libg.a libm.a libcygwin.a libkernel32.a
	ln -s ../${host}/newlib/crt0.o .
	ln -s ../${host}/newlib/libc.a .
	ln -s ../${host}/newlib/libg.a .
	ln -s ../${host}/newlib/libm.a .
	ln -s ../${host}/winsup/libcygwin.a .
	ln -s ../${host}/winsup/libkernel32.a .
)

# Both configure and make need to be told where to find the various pieces.
# Define several variables of the things we need to pass to configure and make.

# These are for building programs that run on $build.
CC_FOR_BUILD=gcc
CXX_FOR_BUILD=gcc

# These are for building programs and libraries that run on $host.
CC="$b2h/gcc/xgcc -B$b2h/gcc/ -isystem $src/winsup/include -isystem $b2h/${host}/newlib/targ-include -isystem $src/newlib/libc/include"
AR=$b2h/binutils/ar
RANLIB=$b2h/binutils/ranlib

# These are for building libraries that run on $target.
CC_FOR_TARGET="$b2t/gcc/xgcc -B$b2t/gcc/ -isystem $src/winsup/include -isystem $b2t/${target}/newlib/targ-include -isystem $src/newlib/libc/include"
GCC_FOR_TARGET="$CC_FOR_TARGET"
CC_FOR_TARGET="$CC_FOR_TARGET"
CXX_FOR_TARGET="$CC_FOR_TARGET"
AS_FOR_TARGET=$b2t/gas/as.new
LD_FOR_TARGET=$b2t/ld/ld.new
AR_FOR_TARGET=$b2t/binutils/ar
NM_FOR_TARGET=$b2t/binutils/nm.new
RANLIB_FOR_TARGET=$b2t/binutils/ranlib
# $DLLTOOL_FOR_TARGET is only needed for win32 hosted systems, but
# it doesn't hurt to always pass it.
DLLTOOL_FOR_TARGET=$b2t/binutils/dlltool
#BISON=$b2h/byacc/byacc

# For go32 cannot use -g because it can overflow coff debug info tables.
CFLAGS=-O
CXXFLAGS=-O

# Ready.  Configure and build.

if [ ! -f $h2t/configure.done ] ; then
    [ -d $h2t ] || mkdir $h2t
    (cd $h2t ; CC="$CC" AR="$AR" RANLIB="$RANLIB" $src/configure --build=${build} --host=${host} --target=${target} --prefix=$rel --exec-prefix=$relexec -v)
    touch $h2t/configure.done
fi

cd $h2t

# `info' already made for FSF releases.
#maketargets="all info"
maketargets=all

make -w ${maketargets} \
	CFLAGS="$CFLAGS" \
	CXXFLAGS="$CXXFLAGS" \
	CC_FOR_BUILD="$CC_FOR_BUILD" \
	CXX_FOR_BUILD="$CXX_FOR_BUILD" \
	CC="$CC" \
	AR="$AR" \
	RANLIB="$RANLIB" \
	GCC_FOR_TARGET="$CC_FOR_TARGET" \
	CC_FOR_TARGET="$CC_FOR_TARGET" \
	CXX_FOR_TARGET="$CC_FOR_TARGET" \
	AS_FOR_TARGET=$AS_FOR_TARGET \
	LD_FOR_TARGET=$LD_FOR_TARGET \
	AR_FOR_TARGET=$AR_FOR_TARGET \
	NM_FOR_TARGET=$NM_FOR_TARGET \
	RANLIB_FOR_TARGET=$RANLIB_FOR_TARGET \
	DLLTOOL_FOR_TARGET="$DLLTOOL_FOR_TARGET"

# All done, install if asked to.

if [ x"$action" = xinstall ] ; then
    make -w install install-info \
	CFLAGS="$CFLAGS" \
	CXXFLAGS="$CXXFLAGS" \
	CC_FOR_BUILD="$CC_FOR_BUILD" \
	CXX_FOR_BUILD="$CXX_FOR_BUILD" \
	CC="$CC" \
	AR="$AR" \
	RANLIB="$RANLIB" \
	GCC_FOR_TARGET="$CC_FOR_TARGET" \
	CC_FOR_TARGET="$CC_FOR_TARGET" \
	CXX_FOR_TARGET="$CC_FOR_TARGET" \
	AS_FOR_TARGET=$AS_FOR_TARGET \
	LD_FOR_TARGET=$LD_FOR_TARGET \
	AR_FOR_TARGET=$AR_FOR_TARGET \
	NM_FOR_TARGET=$NM_FOR_TARGET \
	RANLIB_FOR_TARGET=$RANLIB_FOR_TARGET \
	DLLTOOL_FOR_TARGET="$DLLTOOL_FOR_TARGET"

    # Install cygwin.dll [if built].
    if [ -f $b2h/$host/winsup/new-cygwin.dll ] ; then
	cp $b2h/$host/winsup/new-cygwin.dll $relexec/bin/cygwin.dll
    fi
fi

# Almost done.  Before the toolchain is usable we need to
# - convert the coff files to .exe's,
# - convert file names to follow MSDOS's 8.3 rules,
# - Change \n to \r\n in text files (like headres).
# The package dosrel-1.0 is set up to do all this.
# See ftp://ftp.cygnus.com/pub/embedded/crossgcc/dosrel-1.0.tar.gz

exit $?

Before the tools are usable, a few things must be done:
- convert the binaries to .exe's
- cope with DOS's 8.3 file name restriction

ftp.cygnus.com:/pub/embedded/crossgcc/dosrel-1.0.tar.gz contains a set
of tools to do this.  It works on the "install tree" created by the above
procedure and produces a tar/zip'able tree that is ready to install and use.

Modify the steps in dosrel-1.0/README as follows:

1) Build and install the DOS hosted cross-compiler using the Canadian-Cross
   method.

2) Configure this directory the same way you configured the DOS cross-compiler.
   We build in the source directory here.  The argument to --exec-prefix
   violates DOS's 8.3 rules but the violation is harmless.
   eg: /path/to/binutils-2.7/configure --srcdir=. \
	 --build=$build host=i386-go32 --target=$target \
	 --prefix=$prefix --exec-prefix=$prefix/H-i386-go32 -v

3) Run "make dos-tree GO32_STRIP=/path/to/b-sparc-sun-solaris2-x-i386-go32/binutils/strip.new".

4) Subdirectory `dos-tree' is now ready to copy over to DOS and use.
   You will need to edit `set-env.bat' in the `bin' directory to tell GCC
   and the various pieces where you installed them.

Once the tree is built and installed in MSDOS, you need to set several
environment variables that tell GCC where to find the various pieces.
The following can be copied to a .bat file and run; replace `c:\bar' with
the correct value.

rem The use of GCC_EXEC_PREFIX to find libraries is necessary because
rem LIBRARY_PATH is no longer used for cross-compilers.  We assume
rem cpp, cc1, etc. are in PATH instead.
rem The trailing '/' in GCC_EXEC_PREFIX is important.
set rel=c:\bar
set GCC_EXEC_PREFIX=%rel%/lib/
set C_INCLUDE_PATH=%rel%/include
set CPLUS_INCLUDE_PATH=%rel%/include/cxx;%rel%/include
set INFOPATH=%rel%/info
rem See the go32 docs for more information about the GO32 environment var.
set GO32=EMU %rel%\bin\emu387
set PATH=%rel%\bin;%PATH%

The latest version of djgpp doesn't require go32.exe.  The FSF GNU
toolchain (binutils (?)) and the Newlib library haven't been updated yet.

3.9 Disk space requirements

How much disk space is required?

Disk space requirements vary depending on the host and target.

The source tree occupies about 80MB.
Very roughly:
    binutils 16MB
    gcc 30MB
    gdb 20MB
    libg++ 7MB
    newlib 8MB

A sparc-sunos4.1.4 -x- m68k-coff toolchain requires about 100MB to build,
and about 40MB installed.

4. Frequently Encountered Problems

4.1 installation problem, cannot exec `cpp': No such file or directory

This error message usually appears when GCC has been installed in a place
other than the one it was configured for.  There are two solutions:

1) install GCC in the right place.  You can find out where GCC was configured
to be installed by running `gcc --print-search-dirs'.  It will print something
like this:

install: /calvin/dje/rel/H-sparc-sun-solaris2/lib/gcc-lib/sparc-sun-solaris2/2.7.2.1/
programs: [... omitted ...]
libraries: [... omitted ...]

The `install' line tells you where GCC was configured to be installed
[in this case /calvin/dje/rel/H-sparc-sun-solaris2].

2) Set the environment variable GCC_EXEC_PREFIX to the directory where you
installed GCC.  For example, if you installed GCC in /home/gcc [and file
cc1 lives in /home/gcc/lib/gcc-lib/$target/2.7.2.1 where $target is the --target
argument that was passed to configure], then set GCC_EXEC_PREFIX to
/home/gcc/lib/gcc-lib/.  The trailing '/' is important!

See the GCC info page "Environment Variables" for more information.
e.g. info -f gcc.info -n "Environment Variables"

4.2 64 bit host cross 32 bit target

There are problems in GCC with supporting cross-compiling from a 64 bit
environment to a 32 bit environment.  This is a general weakness in GCC
that is slowly being corrected.  Don't try it unless you're feeling
adventurous.

4.3 Assembler errors while building GCC's enquire or libgcc.a

Assembler errors encountered while building enquire or libgcc.a are usually
caused by GCC [the one you just built] not being able to find the right
assembler.  Have you installed it in a place where GCC can find it?
Were GCC and Binutils configured with the same --prefix/--exec-prefix
arguments?

If the assembler hasn't been installed, the quickest solution is to create
a symbolic link called `as' in the GCC build directory that points to the
assembler to use.

4.4 Unresolved symbols during linking

The first thing to do is confirm you've included all the necessary libraries.

When linking with the GNU linker directly, libgcc.a will not be included.
libgcc.a contains various routines internal to GCC (for example software
floating point support or a 32 bit integer multiply on systems without one).
Add -lgcc as the last argument to GNU ld.  Note that it is not necessary to
add -lgcc when linking with GCC as it will add the -lgcc automatically.
To find out how GCC is invoking the linker, try to link with gcc and pass the
-v option to gcc.

4.5 Where are open, read, write, close, etc. ?

The following is a typical situation people run into when linking their
application.

/usr/local/m68k-coff/lib/libc.a(sbrkr.o): In function `_sbrk_r':
sbrkr.c:60: undefined reference to `sbrk'
/usr/local/m68k-coff/lib/libc.a(makebuf.o): In function `__smakebuf':
makebuf.c:93: undefined reference to `isatty'
/usr/local/m68k-coff/lib/libc.a(filer.o): In function `_open_r':
filer.c:63: undefined reference to `open'
/usr/local/m68k-coff/lib/libc.a(filer.o): In function `_close_r':
filer.c:100: undefined reference to `close'
/usr/local/m68k-coff/lib/libc.a(filer.o): In function `_lseek_r':
filer.c:142: undefined reference to `lseek'
/usr/local/m68k-coff/lib/libc.a(filer.o): In function `_read_r':
filer.c:184: undefined reference to `read'
/usr/local/m68k-coff/lib/libc.a(filer.o): In function `_write_r':
filer.c:226: undefined reference to `write'
/usr/local/m68k-coff/lib/libc.a(fstatr.o): In function `_fstat_r':
fstatr.c:61: undefined reference to `fstat'

Depending upon the target, system calls are not built into newlib's libc.a.
They are too dependent upon the particular target board in use.
Libgloss (which comes with newlib net releases) is intended to be the
repository of such routines and may either provide them in another library
that you must link against or in an object file.

For systems that don't have a need for such routines, just stub
them out. e.g.

int open (char *f, int flags, ...) { errno = ENOSYS; return -1; }

etc.

4.6 How do I pass options from GCC to GAS or GLD?

Sometimes one wants to have GCC pass options to the assembler or linker.
This is done with the -Wa and -Wl arguments to GCC respectively.  For example,
suppose one wanted to pass -foo to GAS.  This is done by passing -Wa,-foo
to `gcc'.  And for the linker, use -Wl,-foo.  Multiple options may be
specified either with multiple uses of -Wa or -Wl, or by separating the
arguments with a comma (e.g. -Wl,-foo,-bar).  If `-foo' takes an argument,
use commas as in -Wa,-foo,fooarg.

4.7 How do I write an interrupt handler in C?

GCC doesn't support writing interrupt handlers (in a general way)
because the FSF doesn't believe this is a useful addition to GCC.
The frequency of use doesn't justify the additional complexity in GCC.
Write a cover function in assembler that calls C code as necessary.
Or, you could embed the necessary assembler at the top and bottom of
a C function, but getting it right may be tricky, and a few bytes of
ROM space will be wasted by the prologue/epilogue that are provided
by GCC.

4.8 How do I write assembler code that works with m68k-aout's leading
    '_' and m68k-coff's lack of leading '_'?

See config/m68k/lb1sf68.asm in the GCC source tree.
It uses macros that prepend (or leave off) the leading underscore
as necessary (and leading '%' for registers).

5. Library Support

5.1 What is libgcc.a?

libgcc.a is a library internal to GCC.  It exists to provide
- subroutines to replace missing hardware functionality
  (for example, say, 32 bit integer multiply)
- software floating point support for chips that don't have hardware
  floating point routines (see 5.3)
- other routines needed to implement language functionality that GCC
  doesn't emit inline code for

5.2 How do I force GCC to emit inline code for memcpy?

You can't [in general].

Some language functionality requires copying a (pseudo-)arbitrary number
of bytes from one place to another (for example, structure assignment in C).
If the GCC port for the target doesn't provide the necessary support,
GCC emits a call to memcpy (or bcopy, depending on the target) to do this,
and currently there is no option to force GCC to emit inline code.  If your
C library doesn't provide the routine, you will need to write one yourself.
GCC may also emit calls to memcpy/bcopy if the object is sufficiently large.

5.3 Why would I choose glibc over newlib (or vice versa)?

There are currently two sources for a C library: Glibc and Newlib.
Both have their pluses and minuses.

Glibc is the GNU libc maintained by the FSF.  It is intended to be a complete
replacement library for native systems.  It includes the routines required
by the C Standard as well as Posix routines.
Newlib is a collection of software from several sources, and was put
together by Cygnus for embedded systems.  It contains the routines required
by the C Standard as well as a math library and misc. other routines.
It is not intended to be a complete replacement library for Unix systems.

Glibc is covered by the LGPL (the GNU Library General Public License).
Newlib is a collection of software from several sources, each with their
own copyrights, but basically it's a Berkeley style copyright.

Glibc, being intended for native Unix environments, does not need to worry
about memory usage as much.
Newlib, being intended for embedded systems, does worry about memory usage
(and is more memory-efficient than glibc).

5.4 What if I need software floating point support?

GCC comes with software floating point support for several embedded targets.

For m68k chips the routines are in config/m68k/{lb1sf68.asm,fpgnulib.c} in
the GCC source tree.  See config/m68k/t-m68kbare for the Makefile additions
that build these routines into libgcc.a

For other chips the routines are in config/fp-bit.c.  See, for example,
config/sparc/t-sparcbare for the necessary Makefile additions.

There is also floatlib.c but it is not currently used for any target.

5.5 Why are several copies of newlib built?

When building m68k-coff (and other embedded targets), one will notice
several copies of libgcc.a, libc.a, and libm.a being built.
Several copies exist so that the correct one can be used when a given option
is used.  For example, when compiling for the m68000, you do not want to link
in a library compiled for the m68020.  And so on.

5.5.1 Is there any way to build only the libraries I need?

Yes.  Depending upon the target, there should be --enable options to
allow you to select which libraries you want to build.  This varies
over time so listing them here might not be useful.  The best way
to find out is to study the config-ml.in script at the top of the
newlib source tree.

6. Using GDB for Remote Debugging

The gdb manual has information on how to do remote debugging with
the targets that it supports.  That is the best place to look.
If you have `info' and the gdb `info' files installed you can run
"info -f gdb.info -n Remote" to view the relevant section.

7. S Records, etc.

7.1 What are S Records?

From the comp.sys.m68k FAQ (http://www.hitex.com/automation/FAQ/m68k):

S-Records are Ascii characters in a protocol developed by Motorola and is
used to transfer data and program code to and from host computers or to store
such information.  Details of this protocol have been archived as s_record.zip
at ftp://nyquist.ee.ualberta.ca/pub/motorola/general, and also at
ftp://ftp.luth.se/pub/misc/motorola/faq as s_record.gz.

7.1 How do I use objcopy to generate S Records?

objcopy can be used to convert an existing file to S Records.
Use --output-target=srec.

7.2 How do I use the linker to generate S Records?

Pass -oformat=srec to GLD.

8. Target Specific Info

8.1 What embedded targets are supported?

Here is a partial list.

They are named by the argument one would use with the --target= option
of `configure'.

a29k-amd-udi
arm-aout
arm-coff
h8300-hms
hppa1.1-hp-proelf
i386-aout
i386-coff
i386-elf
i960-coff
m68k-aout
m68k-coff
mips-ecoff
mips-elf
mips64-elf
powerpc-eabi
sh-hms
sparc-aout
sparclite-aout
sparclite-coff
sparc64-elf

9. Operating systems for embedded systems

9.1 RTEMS

RTEMS is a freely available real-time executive with multiprocessor
capabilities.  RTEMS was designed to provide performance and capabilities
similar to those of the best commercial executives.  The directive
execution times and other critical performance measures such as interrupt
latency are comparable to those of commercial executives.  It was
developed by On-Line Applications Research Corporation (OAR) under
contract to the U.S. Army Missile Command.  It is based on the now defunct
(Real-Time Executive Interface Definition) RTEID and as a result the API
is similar to pSOS+.  RTEMS has a number of features which exceed the
capabilities of RTEID including optional rate monotonic scheduling
support, binary semapahores with priority inheritance, watchdog timer
functions.  Current efforts include adding support for POSIX threads and
real-time extensions. 

There are two implementations of RTEMS using the same design -- C and Ada.
The current release includes support for the m68k, i960, i386, HP PA-RISC
and what the RTEMS developers calls the UNIX simulator.  The UNIX
simulator version allows RTEMS applications to be run as UNIX processes --
signals are used to simulate interrupts, setjmp for context switches, etc. 
The next snapshot will include support for the PowerPC and SPARC. 

RTEMS does not currently have a number of "packaging" features 
which are available in commercial executives.  The top items on 
this list are networking, filesystems, and a tasking aware debugger.

WWW: http://www.rtems.army.mil
FTP: ftp://ftp.rtems.army.mil
     ftp://ftp.cygnus.com/pub/embedded/rtems

10. How to get help

10.1 General questions

If the topic is related to using the tools in a cross-compiler environment
then this list is an excellent place to look for help.  If you've found
a bug in a particular piece of software, it is best to report the bug
to the appropriate list (e.g. bug-gcc) rather than this list.

Be careful about reporting bugs associated with patches you have applied
to GCC (or any GNU software).  The FSF has not sanctioned these patches
and shouldn't have to respond to bug reports for such patches.  Sometimes
it is hard to tell, in which case use your best judgement.  When sending
bug reports to bug-gcc, always mention all patches applied.

10.2 Online documentation

Documentation for the GNU tools may be found in
http://www.cygnus.com/library-dir.html.

10.3 Bug reporting

Here is a list of the tools and their bug reporting addresses:

Binutils: bug-gnu-utils@prep.ai.mit.edu
GCC:      bug-gcc@prep.ai.mit.edu
G++:      bug-g++@prep.ai.mit.edu
Glibc:    bug-glibc@prep.ai.mit.edu
GDB:      bug-gdb@prep.ai.mit.edu
Newlib:   newlib@cygnus.com

When reporting a bug, please read the documentation that comes
with the software to find out how to report a bug.  If you've installed
`info' and the GCC info files, "info -f gcc.info -n Bugs" should zip you
right to the page you need to read for GCC.

Failing that, always include the following information:
- version number (e.g. gcc-2.7.2.1)
- configuration (the arguments you passed to `configure')
- type of system you are compiling on (e.g. i386-linux, sparc-solaris2),
  ideally this is the result of the `config.guess' program that is included
  in the source tree
- (in the case of gas, gcc, glibc, and newlib) preprocessed source that
  triggers the bug.  Preprocessed source can either be obtained by passing
  -E to GCC and sending the output, or by passing -save-temps to GCC and
  sending the resulting .i file (or .ii file in the case of g++).
  It is generally much better to include the preprocessed source rather than
  say "GCC can't compile file foo.c from program Bar version 4.2".
- complete list of options passed to the program (e.g. gcc -g -O2 ...).
- the text of the error message [as output by the program, do not edit it
  for brevity]

10.4 Other mailing lists, web sites, newsgroups, etc.

djgpp

    Mailing list: djgpp@delorie.com
    Web site:     http://www.delorie.com/djgpp/
    Newsgroup:    comp.os.msdos.djgpp

gnu-win32

    Mailing list: gnu-win32@cygnus.com

miscellaneous newsgroups

    comp.arch.embedded
    comp.sys.m68k

FIXME: Others?

11. Glossary

Canadian Cross

	This is a cross compiler where build machine != host machine.
	See section 3.6 for more information.

cross compiler

	This is a compiler that builds programs for a machine different
	than the one the compiler is run on.  For example, an i386-linux
	cross m68k-coff compiler is one where GCC runs on an i386-linux
	machine and compiles programs for running on m68k-coff machines.

build machine

	This is the machine the toolchain is being built on.
	In the case of a Canadian Cross, it is not the same as the
	host machine.

host machine

	This is the machine the toolchain programs (GCC, GAS, etc.)
	will run on.  In the case of a cross compiler, this is not the
	same as the target machine.

native compiler

	This is a compiler where host == target.

target machine

	This is the machine the toolchain builds programs for.

FIXME: Others?

12. Contributors.

The following people have contributed to this FAQ.  Thanks!

Steve Baldwin, baldwins@stimpy.fp.co.nz
Brian Carlstrom, bdc@ai.mit.edu
Steve Chamberlain, sac@cygnus.com
DJ Delorie, dj@delorie.com
Jason Molenda, crash@cygnus.com
Ken Raeburn, raeburn@cygnus.com
Rob Savoye, rob@cygnus.com
Stan Shebs, shebs@cygnus.com
Joel Sherrill, joel@oarcorp.com
Ian Taylor, ian@cygnus.com

If I've left anyone out, please let me know.
