How to test GCC on a simulator

Several GCC targets can be tested using simulators. These allow you to test GCC for a specific processor for which you don't have access to hardware, or for targets that have general characteristics you'd like to test, like endianness or word size.

All of the instructions here start out from a directory we'll call ${TOP}, which is initially empty.

Set up sources

Testing with a simulator makes use of a combined tree here; you can't easily build newlib, required for simulator testing, outside of a combined tree, and the build of the other components is easiest in a combined tree. A combined tree is not a requirement for testing with a simulator; other alternatives exist. For example, binutils and simulators can be built for the target, and installed beforehand. However, we use a combined tree here as it's a convenient example and does not require separate installation steps or parameters.

The combined tree contains GCC sources plus binutils and newlib for the generated code and sim for the simulators. If you already build with a combined tree you can use your current setup; if not, these instructions will get you the sources you need.

Check out initial trees

We check out each component from each separate project's repository, but it's possible to use release or snapshot tarballs, with an increased risk of version lag causing configuration framework mismatches in the combined tree. If you don't yet have either tree you'll need to do some initial check-outs.

Check out mainline GCC:

cd ${TOP}
git clone git://gcc.gnu.org/git/gcc.git gcc
# This makes sure that file timestamps are in order initially.
cd ${TOP}/gcc
contrib/gcc_update --touch

Check out the newlib (src) tree:

cd ${TOP}
git clone https://sourceware.org/git/newlib-cygwin.git newlib

Check out the sim and binutils tree:

cd ${TOP}
git clone git://sourceware.org/git/binutils-gdb.git sim+binutils

Update trees

You can update existing CVS, git and subversion trees rather than starting from scratch each time. Update the GCC tree using the gcc_update script, which touches generated files and handles directory changes in the tree. Be sure to do this from the directory in which you did the original check-out, NOT in the combined tree:

cd ${TOP}/gcc
contrib/gcc_update

Update the newlib src tree with the same sequence of commands that you used to check out that tree initially (edits in the src tree will be preserved). Make sure you do not do this from within the combined tree. For the binutils+sim tree a normal git pull command will do. Remove the combined tree and re-create it. (Beware, edits in the combined tree will be lost.)

Create a combined tree

Create a tree that consists of all of the files from the GCC and binutils/sim/newlib source trees (including several simulators in the sim directory), with the GCC files overriding the binutils/sim/newlib files when there's a conflict, and binutils and with sim overriding newlib files. It's done this way because the GCC files are the master copy, while binutils and gdb move faster than newlib. To save on disk space, these commands actually make a tree of hard links rather than duplicating all the files:

cd ${TOP}
rm -rf combined
mkdir combined
cd src && find . -print | cpio -pdlm ../combined && cd ..
cd sim+binutils && find . -print | cpio -pdlmu ../combined && cd ..
cd gcc && find . -print | cpio -pdlmu ../combined && cd ..

Build it

Make sure the building prerequisites for GCC are met, for example a host GCC no earlier than 3.4 or later, with C++ support enabled.

The target name suitable for the simulator is usually `*-elf' for a target `*'. There are some exceptions, for instance on powerpc it's powerpc-eabi or powerpc-eabisim, and for arm, the arm-elf support is obsoleted. Here we build arm-eabi, but we avoid gdb and build only for the C and C++ languages, because some of the targets mentioned below will otherwise fail building.

cd ${TOP}
mkdir build install
cd build
../combined/configure \
    --target=arm-eabi --disable-gdb --enable-languages=c,c++ --prefix=${TOP}/install
make

Test it

The only trick here is that you want DejaGNU to use the simulator rather than trying to run the output on the build system. For example:

cd ${TOP}/build
make check-gcc check-target-libstdc++-v3 RUNTESTFLAGS=--target_board=arm-sim

cd ${TOP}/build
make check RUNTESTFLAGS=--target_board=arm-sim

The only reliable way (apart from guessing that it's probably `*-sim') to find out the name of the target board is to look in the DejaGNU sources, in /usr/share/dejagnu/baseboards, for something that looks right. Or you can use this table of combinations that at one time compiled, usable as test-targets with the instructions above.

You can compare your test results against the archived results linked below to detect major problems. As always, if you're testing a patch you should compare your results with and without the patch.

The target characteristic can help you determine which targets to use to broaden the scope of your testing. A cc0 target uses a single condition code register, cc0, which is set as a side effect of most instructions. The compiler cannot insert other instructions between the instruction that sets cc0 and the one that uses it. Because of this, a cc0 target causes significantly different code to be generated and can matter more than word size and endianness in terms of detecting new breakage.