# Introduction

The GNUPro® Toolkit for eCos is a complete solution for C and C++ development for the SuperH® RISC family of chips. The tools include the compiler, assembler, linker, and interactive debugger. In addition to this manual, please read "Getting started with eCos." This document consists of the following sections:

- Introduction
An introduction to the features of the GNUPro Toolkit for eCos.

- Reference
Describes the ABI and SuperH RISC-specific attributes of the main GNUPro tools.

- Bibliography

## Tool naming conventions

Cross-development tools in the Cygnus GNUPro Toolkit normally have names that reflect the target processor and the object file format output by the tools (for example, ELF). This makes it possible to install more than one set of tools in the same binary directory, including both native and cross-development tools.
The complete tool name is a three-part hyphenated string. The first part indicates the processor family ('sh'). The second part indicates the file format output by the tool ('elf'). The third part is the generic tool name ('`gcc`'). For example, the GCC compiler for the SuperH RISC is 'sh-elf-gcc'.
The SuperH RISC package includes the following supported tools:

Tool Description | Tool Name
GCC compiler | sh-elf-gcc
C++ compiler | sh-elf-g++
GAS assembler | sh-elf-as
GLD linker | sh-elf-ld
Binary Utilities | sh-elf-ar sh-elf-nm sh-elf-objcopy sh-elf-objdump sh-elf-ranlib sh-elf-size sh-elf-strings sh-elf-strip
GDB debugger | sh-elf-gdb

The binaries for a Windows NT hosted toolchain are installed with an '.exe' suffix. However, the '.exe' suffix does not need to be specified when running the executable.

## Toolkit features

The following describes features of the GNUPro Toolkit for the SuperH RISC.

### Processor version(s)

SH1, SH2, SH3, SH3e, and SH4

### Hosts Supported

CPU | Operating System | Vendor
x86 | Redhat 5.x, 6.0 | Redhat
x86 | Windows NT 4.0 | Microsoft

### Object file format

The SuperH RISC tools support the ELF object file format. Refer to Chapter 4, System V Application Binary Interface (Prentice Hall, 1990.). Use 'ld' (refer to Using LD in GNUPro Utilities ) or 'objcopy' (refer to The GNU Binary Utilities in GNUPro Utilities ) to produce S-records.

## GNUPro on Windows NT

### Windows environment settings

The Windows NT hosted toolchain requires the following environmental settings to function properly. Assuming the release is installed in: C:\cygnus\gnupro\i686-cygwin32\sh-elf\<release>
SET PROOT=C:\cygnus\gnupro\i686-cygwin32\sh-elf\<release>
SET PATH=%PROOT%\H-i686-cygwin32\bin;%PATH%
SET INFOPATH=%PROOT%\info
REM Set TMPDIR to point to a ramdisk if you have one
SET TMPDIR=C:\TEMP

Note: The variable '<release>' indicates the release directory name found on the CD.

A working environment can be established by using the following shortcut from the Windows Start menu:
Programs->Cygnus eCos->eCos Development Environment
This will bring up a window running "bash", and your Windows environment will be automatically set up.

### Rebuilding from source

If you wish to rebuild the tools from the source code, see the section "Rebuilding the GNUPro tools from source."

### Case Sensitivity

The following strings are case sensitive under Windows NT:

- command line options
- assembler labels
- linker script commands
- section names
- file names within makefiles

The following strings are not case sensitive under Windows NT:

- gdb commands
- assembler instructions and register names

Case sensitivity for Windows NT is dependent on system configuration. By default, file names under Windows NT are not case sensitive.

## GNUPro on Unix

In the following examples two variables have been used. The variable '<version>' should be replaced with the directory name that the installer made when the GNUPro tools were installed (or eCos was installed). For example, something like
'ecos-99r1-990828' or 'gnupro-99r1p1'. The variable '<host>' should be replaced with the "host triplet" of your build system. You can determine the host triplet by running the script 'config.guess' at the top of the source tree. Typical examples include 'i686-cygwin32', 'i686-pc-linux-gnu' or 'sparc-sun-solaris2.6'.

### eCos Developer's Kit users

The eCos Developer's Kit is supplied with tested prebuilt development tools for this host and target. By default, the installation script supplied in the tools distribution will install the tools in

> /usr/cygnus/<version>/H-<host>/bin.

If you wish to rebuild the tools from the sources, then please see the section "Rebuilding the GNUPro tools from source".

### Sourceware distribution users

The GNUPro Tools for Redhat Linux are supplied in a ZIP format file. Detailed instructions for installation can be found on the eCos sourceware site:

> http://sourceware.cygnus.com/ecos/

By following the instructions there, you should have the sources installed in:

> /usr/cygnus/<version>/src

and the tools built in:

> /usr/cygnus/<version>/H-<host>/bin

### Unix environment settings

After the tools have been built (if applicable) and installed, we recommend you have the following settings in your appropriate shell startup script, assuming the tools were installed in '/usr/cygnus/<version>'.
For Bourne shell compatible shells:

> PROOT=/usr/cygnus/<version>
> PATH=$PROOT/H-<host>/bin:$PATH
> INFOPATH=$PROOT/info:${INFOPATH-/usr/local/info:/usr/info}
> MANPATH=$PROOT/man:${MANPATH-/usr/local/man:/usr/man}
> export PATH INFOPATH MANPATH

For C-shell compatible shells:

> setenv PROOT /usr/cygnus/<version>
> if ( "$?MANPATH" == "0" ) then
> setenv MANPATH "/usr/local/man:/usr/man"
> endif
> if ( "$?INFOPATH" == "0" ) then
> setenv INFOPATH "/usr/local/info:/usr/info"
> endif
> setenv MANPATH $PROOT/man:$MANPATH
> setenv INFOPATH $PROOT/info:$INFOPATH
> set path = ( $PROOT/H-<host>/bin $path )

### Rebuilding from source

If you wish to rebuild the tools from the source code, see the next section "Rebuilding the GNUPro tools from source."

## Rebuilding the GNUPro tools from source

This section outlines the steps to rebuild the GNUPro tools from source code.
In the following examples two variables have been used. The variable '<version>' should be replaced with the directory name that the installer made when the GNUPro tools were installed (or eCos was installed). For example, something like
'ecos-99r1-990828' or 'gnupro-99r1p1'. The variable '<host>' should be replaced with the "host triplet" of your build system. You can determine the host triplet by running the script 'config.guess' at the top of the source tree. Typical examples include 'i686-cygwin32', 'i686-pc-linux-gnu' or 'sparc-sun-solaris2.6'.
If you wish to rebuild the tools from the sources, then assuming the sources have been installed into '/usr/cygnus/<version>/src', the steps to take are as follows:

1. On Windows hosts, you must start a Cygwin bash shell. Customers with the eCos Developer's Kit can invoke a bash shell using the following shortcut:

> Start->Programs->Cygnus eCos->eCos Development Environment

2. You must have a native GNU compiler ('gcc') installed on your system.

> On Windows hosts this will be part of your Cygwin tools installation.

On Unix hosts, if you have not been provided with a native GNU compiler, you will need to build one from the sources provided. You can do this by following these instructions but omitting the '--target' parameter in step 4, and altering step 5 to:

make -w all-gcc install LANGUAGES=c > make.out 2>&1

Warning:
If you have '.' in your PATH environment variable, make sure that it comes after the GNU native compiler tools directory. The following build procedure will fail if '.' is ahead of the GNU native compiler tools in the path.

3. Create an object directory for your builds:

> mkdir /tmp/build
> cd /tmp/build

4. Configure the tools, saving the output to configure.out. Users of the 'csh' and 'tcsh' shells should replace
'> filename.out 2>&1' with '>& filename.out' throughout:

> /usr/cygnus/<version>/src/configure -v \
> --prefix=INSTALLDIR \
> --exec-prefix=INSTALLDIR/H-<host> \
> --target=TARGET > configure.out 2>&1

INSTALLDIR is the installation directory into which the tools should be installed. If the old tools were to be replaced completely, this could be set to '/usr/cygnus/<version>', although if this is done we strongly recommend moving the old tools to a safe place beforehand.
TARGET is the "target triplet" you are compiling for. This is the same as the tool name prefix given in the earlier section "Tool naming conventions."

5. Build and install the tools, saving the output to make.out:

> make -w all install LANGUAGES="c c++" > make.out 2>&1