CrossGCC Frequently Asked Questions =================================== Version: 0.8.1 Last Updated: 970428 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 " 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 " 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 -p1 <../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=$i/bin/${target}-ar \ RANLIB_FOR_TARGET=$i/bin/${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 " 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.