Installation Procedure
**********************

Introduction
============

This chapter describes the process of installing and configuring RTEMS and a cross-development environment based on freely available tools and libraries.

RTEMS FTP Site Organization
===========================

RTEMS is distributed only via anonymous ftp.

This section will discuss how to navigate the RTEMS ftp site and unarchive the files in the RTEMS and GNU package distributions.  All example commands will be given in a shell independent fashion unless otherwise noted.

Throughout the rest of this manual <RTEMS_distribution> will be used as the parent of components within the RTEMS distribution.  For persons using the ftp distribution found on the primary ftp site for RTEMS, <RTEMS_distribution> is ftp://ftp.OARcorp.com/oarcorp/rtems/VERSION.

The archive files for RTEMS Release VERSION are found under the directory <RTEMS_distribution>.  This directory contains the files which comprise this relase as well as any patches which may be required for other tools.

The complete source code and documentation set for the C language implementation of RTEMS is provided.

Documentation other than this on-line version is available to OAR support customers.  Please contact OAR for more information.

Unarchiving the RTEMS and GNU Components
========================================

Many of the components of the RTEMS release are "tarred, zipped" files and have the .tar.gz or .tgz extension. The GNU zip package is required to unarchives these files on the RTEMS ftp site.  If this package is not installed, the source can be found in the files ftp://prep.ai.mit.edu/pub/gnu/gzip-1.2.4.shar or ftp://prep.ai.mit.edu/pub/gnu/gzip-1.2.4.tar.  It may be restored using a command similar to the following:

     tar xvf gzip-1.2.4.tar

     OR

     sh gzip-1.2.4.shar

This will create a subdirectory gzip-1.2.4 in the current directory.  Please examine the files README and INSTALL and follow the instructions provided there.

[Note: The GNU tools follow a standard packaging procedure They will unarchive into a directory based on the package name and version number.  For detailed instructions on compilation and installation of the GNU tools, please refer to the instructions for each GNU tool.]

Files which have been "tarred, zipped" (i.e.  .tar.gz or .tgz extension) may be unarchived with a command similar to one of the following:

     gzcat <file>.tgz | tar xvof -

     OR

     gunzip -c <file>.tgz | tar xvof -

     OR

     gtar xzvf <file>.tgz

NOTE: gunzip -c is equivalent to gzcat, while gtar is GNU tar.

Given that the necessary utility programs are installed, any of the above commands will extract the contents of <file>.tar.gz into the current directory.  All of the RTEMS components will be extracted into the subdirectory rtems-VERSION. To view the contents of a component without restoring any files, use a command similar to the following:

     gzcat <file>.tgz | tar tvf -

Installing a Cross-Development GNU Toolset
==========================================

This sections describes how to build and install the FSF GNU tools for use as a cross-compilation system.  These tools are used by the RTEMS developers.  Every effort has been made to make these instructions accurate and complete.  However, it is recommended that the individual doing the installation read the appropriate installation notes for each of the tools in the cross toolset.  This will help insure that there are no special requirements for a particular host.

If the host and target processors are the same, then it may be possible to use the host development tools.  An example of this scenario is using a SPARC based workstation to develop an RTEMS application for the SPARC processor.  Although the native toolset is useable in this scenario, it is ultimately more desirable to build a toolset specifically for the embedded environment.

Instructions for building a cross environment using the GNU tools is provided in the crossgcc FAQ available from ftp.cygnus.com in /pub/embedded/crossgcc.  It is recommended that the user following these instructions.

After the cross development toolset has been built and installed, it will be necessary to modify the environment of each RTEMS application developer to reflect at least the path of the newly installed cross development toolset.

The documentation for the FSF GNU and Cygnus tools is formatted using TeX.  The RTEMS developers use TeX 3.14t3 to format the manuals for their own use.  This document does not contain instructions on the acquisition or installation of TeX and supporting tools.

NOTE: For "UNIX" processors, the native compiler binary utilities should be used.

Installing RTEMS
================

For instructions on building and installing RTEMS, please refer to the file README.configure in the source distribution.