Progressive p3-921001
*********************

Overview
********

Cygnus Support Developer's Kit

Progressive Release p3-921001

This is the first Progressive Release where several standard cross-development configurations are available.  A cross-development configuration is for developing software to run on a different machine (the target) than the development tools themselves (which run on the host)---for example, you might use a SPARCstation to generate and debug code for an AMD 29K-based board.

Naturally, we also continue to offer native configurations, where the tools and your code run on the same kind of machine.

This table shows the host/target combinations available:

            \ HOST |                   DEC   IBM   SGI
     TARGET  \     | SUN3  SUN4  SOL2  STN   RS6K  IRIS  DOS  HP300  HP700
     --------------+--------------------------------------------------------
     Native        |  X     X     X     X     X     X
     68k VxWorks   |  X     X           X     X     X           X      X
     68k a.out     |  X     X           X                 X            X
     68k coff      |        X           O                 O
     29k UDI       |        X                             X
     ix86 a.out    |        X           O                 O
     i960 VxWorks  |        O           O     X                        O
     i960 Nindy    |        O           O
     SPARC VxWorks |        X
     SPARC a.out   |        O

     X     = on the shelf
     O     = may be custom built
     68k   = 68000, 68010, 68020, 68030, 68040
     ix86  = 386, 486
     i960  = KA, KB, CA
     SPARC = SPARC, SPARClite

Your tape is labeled with host=PLATFORM to indicate the host for that configuration.  To avoid ambiguity, these names use a three-part naming scheme which identifies the CPU, vendor, and operating system:

Sun-3
     m68k-sun-sunos411

Sun-4
     sparc-sun-sunos411

Solaris 2
     sparc-sun-solaris2

DECstation
     mips-dec-ultrix

SGI Iris
     mips-sgi-irix4

IBM RS6000
     rs6000-ibm-aix

HP-700
     hppa1.1-hp-hpux

HP-300
     m68k-hp-hpux

DOS
     i386-gen-dos

If you have a cross development tape, the label also indicates target=MACHINE to identify the target for that configuration.  A two-part naming scheme identifies CPU and object code format or cross-development environment:

Motorola 680x0 family
     m68k-aout---a.out object code format. m68k-coff---coff object code format. m68k-vxworks---VxWorks environment.

Intel 960 family
     i960-vxworks---VxWorks environment. i960-nindy---Nindy monitor.

AMD 29000 family
     a29k-amd-udi---UDI monitor interface.  (To use the MINIMON interface, use this configuration with the program MONTIP, available from AMD at no charge.)

SPARC family
     sparc-vxworks---VxWorks environment. sparc-aout---a.out object code format.

Intel 386 family
     i386-aout---a.out object code format.

In cross-development configurations, each tool in the Developer's Kit is named with the identifying string as a prefix.  For example, if the C compiler is configured to generate COFF format code for the Motorola 680x0 family, the compiler is installed as m68k-coff-gcc.

Closest FSF Versions
********************

Cygnus Support devotes much of its effort to integrating and improving free software.  In fact, Cygnus employees are the primary developers of several important components of the GNU tool-chain (on behalf of the Free Software Foundation).  However, for programs whose FSF releases are issued elsewhere, our releases are often slightly ahead of the nearest corresponding FSF version.  We reintegrate our sources with the FSF as frequently as possible without compromising the stability of the integrated toolchain.

These are the closest corresponding FSF releases of the GNU development tools:

Program
     Closest FSF version

gcc/g++
     pre-2.3

gdb
     4.6.5 (maintained at Cygnus)

make
     3.62.16 (not supplied for DOS hosts)

libg++
     2.2.2 (maintained at Cygnus)

For all cross-development configurations, and on Sun-4 (other than Solaris-2) and Sun-3 native configurations, these supporting programs are also included:

as
     1.91

ld
     1.97.1 (maintained at Cygnus)

Binary Utilities
     1.97 (maintained at Cygnus)

A Progressive Release of GNU Emacs is also available separately from Cygnus Support for selected hosts.

New in This Release
*******************

Cross-Development
     The focus on cross development in release p3-921001 makes standard support available for the first time for many embedded systems applications.  The additional testing, configuration, and cleanup work required has also made the native configurations even more robust.

New Hosts
     There is a new native configuration, the Solaris-2 environment (SunOS 5.0), and three new hosts for cross-development only---HP-300, HP-700, and DOS.

C library
     We have assembled, improved, and documented a standard C subroutine library libc.a and C mathematical subroutine library libm.a. These are not GNU libraries, so there are no additional code distribution requirements for programs that use them.

C++
     g++ and libg++ continue to grow more robust.  You can compile many popular applications and class libraries with GNU C++, including groff and Rogue Wave.

     This release of g++ is still unable to build the entire NIHCL and InterViews libraries, but the g++ renovation project (underway) will address these incompatibilities.

GDB symbol quoting and completion
     The GNU debugger will interactively help you select among similar (or overloaded) names, with extensions to its command-line completion facilities to apply completion to symbols, and to allow you to quote symbols in order to alter the scope of completion.

Limitations and Warnings
************************

In this release, some of the supported systems don't run some of the supporting GNU programs, and one system (the RS/6000) has a number of special requirements.

Install remove may go too far
=============================

The Install script that comes with your Developer's Kit release can also be used to remove either the source, or the binaries, after installation.  However, in this release, Install remove is not selective enough.  If you install more than one configuration of the release in the same directory (for example, under the default directory /usr/cygnus), ./Install remove will delete all installed configurations; there is no way to select just files from one or another package.

We will rectify this problem in future releases.

Programs not Available
======================

Progressive p3-921001 does not include the following supporting programs on the native configurations for Solaris-2, Iris, DECstation, or RS/6000.  You must use the native equivalents, supplied by the machine vendors, with the GNU compiler:

AS
     assembler

LD
     linker

Binary Utilities
     ar, nm, objdump, ranlib, size, strip

RS/6000 Assembler Upgrades
==========================

Debugging code compiled with GCC on the RS/6000 requires that you upgrade the AIX assembler /bin/as with a replacement that is available from IBM.  Without the upgrade, you can still compile your code, but gcc -g ... will not work.

Any IBM RS/6000 customer can order and get the replacement assembler, and install it on one or more machines.  It is distributed both on diskette and via VNET, for downloading via ftp.  VNET distribution may be desirable if you have a friendly IBM representative nearby with a networked VM machine.

In either case, to order the replacement assembler from IBM, first execute lslpp -h bos.obj to determine your release level.  (Look on the ACTIVE line for something like 03.01.0005.0012.) Then (in North America) call IBM Support at 800--237--5511.  Ask for emergency shipment of the RS/6000 AIX fix for APAR IX26107.  They may ask you to verify that it's a fix for ``Don't allow .csect name[BS] or [UC]''; say yes.  They may also ask you for your customer number.  If you do not know it, you will still be able to get the fix, but you will have to be persistent.

You will receive a tar or tar.Z file containing an assembler plus installation instructions.

If you tell them you're running AIX version 3.2, you may be told that no fix is available yet.  In fact the 3.1.5 fix works fine on version 3.2.  Request it anyway.

IBM has corresponding support organizations outside of North America. If you are not in North America, call your IBM branch office and ask them to put you in touch with the department that handles emergency fixes for AIX on the RS/6000.  If that doesn't work, ask for the department that handles software defect support for AIX on the RS/6000. Then ask for the emergency APAR fix.

Cross-Development: Special Considerations
*****************************************

Using the Developer's Kit in one of the cross-development configurations may require more attention to two areas.  (A cross-development configuration is for developing software to run on a different machine than the development tools themselves.)

First, as a prerequisite to development, you may need to set up the target environment.  Second, if you use LIBG++ (the GNU C++ class libraries), you may want to consider special licensing terms from the FSF for your product.

Setting up the target environment
=================================

To allow our tools to work with your target environment (except for VxWorks, which provides full operating system support), you need to set up:

  * the C run-time environment (described below).

  * stubs or minimal versions of operating-system subroutines for the C subroutine library.  See System Calls (The Cygnus C Support Library).

  * a connection to the debugger.  See Remote Debugging (Debugging with GDB).

The C Run-Time Environment (crt0)
---------------------------------

To link and run C or C++ programs, you need to define a small module (usually written in assembler as crt0.s) that makes sure the hardware is initialized for C conventions before calling main.

You will need this information about your target:

  -- A memory map.  What memory is available, and where?

  -- Which way does the stack grow?

  -- What output format will you use?

At a minimum, your crt0 must do these things:

 1. Define the symbol start (_start in assembler code). Execution will begin at this symbol.

 2. Set up the stack pointer sp.  It is largely up to you to choose where to store your stack within the constraints of your target's memory map.  Perhaps the simplest choice is to choose a fixed-size area somewhere in the uninitialized-data (bss) section.  Remember that whether you choose the low address or the high address in this area depends on the direction your stack will grow.

 3. Initialize all memory in the uninitialized-data (bss) section to zero.  The easiest way to do this is with the help of a linker script (see Command Language (Using LD)). Use a linker script to define symbols such as bss_start and bss_end to record the boundaries of this section; then you can simply loop between them in crt0.

 4. Call main.  Nothing else will!

A more complete crt0 might also do the following:

 5. Define an _exit subroutine (this is the C name; in your assembler code, use the label __exit).  Its precise behavior will depend on the details of your system---and on your choice.  Possibilities include trapping back to the boot monitor, if there is one; or to the loader, if there is no monitor; or even back to start.

 6. If your target has no monitor to mediate communications with the debugger, crt0 is where you must set up the hardware exception handler.  See The GDB remote serial protocol (Debugging with GDB), for details on how to use GDB's generic remote-target facilities for this purpose.

 7. Perform other hardware-dependent initialization; for example, initializing an MMU or an auxiliary floating-point chip.

 8. On some systems, copy microcode from ROM to RAM; see your target manufacturer's hardware manual if you're not certain whether this is needed.

 9. Define low-level input and output subroutines.  For example, crt0 is a convenient place to define the minimal assembly-level routines described in System Calls (The Cygnus C Support Library).

LIBG++ licensing terms
======================

LIBG++ is licensed under the GNU Library General Public License (LGPL); for embedded-system developers who use this library, the automatically available terms defined there may be inconvenient.  (This issue does not arise for the C subroutine libraries in cross-development configurations of the Cygnus Developer's Kit.  The C subroutine libraries are not LGPL libraries---Cygnus has developed them or assembled them from sources that require only copyright acknowledgement.)

The GNU Library General Public License is designed to promote software sharing among computer users.  As a consequence, its terms require that you make the source code for the library available with any program you distribute that uses a GNU library, and that you allow users of your programs to relink them with modified or updated copies of the library.

These terms work well for programs that run on general-purpose computer systems.  But they may be impractical for programs in embedded systems, where the end user may not even be aware that computers and programs are involved in a product.

The Free Software Foundation (FSF) is aware of this problem, and has expressed willingness to grant permission for library use in embedded systems under alternative licensing terms.  However, the LGPL is the only license that is automatically available; to arrange for alternative terms for your embedded application, you must contact the FSF directly. Write to

     Free Software Foundation, Inc.
     675 Mass Ave.
     Cambridge, MA
     USA        02139

You can also send electronic mail to gnu@gnu.ai.mit.edu.

The Foundation will want to know enough about your application to ensure that the ordinary LGPL terms do not make sense in your case, and that your intended use does not contravene the goals of promoting software sharing, and of preserving the free status of all derivatives of GNU software.  You can save time by making certain you supply this information in your initial letter.

For example, you can use a letter of this form, signed by an authorized officer of your organization:

     1 April 2002

     Dear FSF Staff:

     Our company, SmallZap Inc., builds intelligent electronic flea traps. Our product plans call for use of the GNU C++ Library (LIBG++) in writing the software for the embedded controller.

     Our market research indicates that serving our customers' immediate needs requires a device with the simplest possible controls. Therefore, the device cannot be reprogrammed, and it would be impractical, confusing, and pointless to supply source code for this Library, or to supply a relinkable form of our own code.

     Accordingly, we request permission from the FSF to distribute devices that use programs linked with the Library without meeting these two requirements of the GNU Library General Public License (LGPL).

     SmallZap Inc. acknowledges that this permission is not transferrable to any other organization or individual.

     SmallZap Inc. hereby certifies that we will meet the full LGPL terms in any software distributions intended for general-purpose computers, or with any product where the programs are on rewritable media.

     SmallZap Inc. hereby acknowledges that there is NO WARRANTY for GNU Libraries, and assumes all liability for its use of GNU Library code in our embedded controllers.

     The undersigned is an authorized representative of SmallZap Inc.

     yours,

          AUTHORIZED SIGNATURE
          S. M. Zap
          Debugging Officer
          SmallZap Inc.

Rebuilding From Source
**********************

All Cygnus products are free software; your Developer's Kit includes complete source code for all programs.

Cygnus Support has implemented an automatic configuration scheme to adapt the programs to different environments.

Rebuilding the programs from source requires these steps:

 1. configuration

 2. compilation

 3. installation

For example, executing the following commands in sequence will rebuild and install a Sun-4 native version of all the tools in a nonstandard directory:

     eg$ cd p3-921001/src

     eg$ ./configure sun4 -prefix=/local/gnu
     Created "Makefile" in INSTALLDIR/p3-921001/src

     eg$ make clean all info install install-info >make.log
     ... output for make steps follows

We discuss each step in detail in the following sections.

Configuration
=============

You can configure the software in this release by using the shell script called configure.  The shell script requires one argument: the host type.  There are also several possible options, including a -target= option to configure for cross-system development.

Specifying Names for Hosts and Targets
======================================

The specifications used for hosts and targets in the configure script are based on a three-part naming scheme, but some short predefined aliases are also supported.  The full naming scheme encodes three pieces of information in the following pattern:

     ARCHITECTURE-VENDOR-OS

For example, you can use the alias sun4 as a HOST argument or in a -target=TARGET option, but the equivalent full name is sparc-sun-sunos4.

     Warning: configure can represent a very large number of combinations of architecture, vendor, and OS.  There is by no means support for all possible combinations!

configure Options
=================

This section summarizes the configure options and arguments. Your Developer's Kit contains full online documentation for the Cygnus configure system.  See Using Configure (configure.info), to read about configure in more detail, including information on how the configure options relate to Makefile variables.

     configure [-prefix=DEST]
               [-exec-prefix=BINDEST]
               [-srcdir=PATH]
               [-norecursion]
               [-target=TARGET]
               HOST

-prefix=DEST
     DEST is an installation directory path prefix, the root for the directories where make install will place things.  After you configure with this option, make install install-info will install info files in DEST/info, man pages in DEST/man, and---unless you also use -exec-prefix---compiled programs in DEST/bin, and libraries in DEST/lib.  If you specify -prefix=/local, for example, make install puts the development tools in /local/bin.

     WARNING: the default DEST path prefix in the source is not the same as the prefix for the preconfigured binaries distributed by Cygnus.  If you do not use -prefix, the installation directory is /usr/local.

-exec-prefix=BINDEST
     -exec-prefix serves the same purpose as -prefix, but affects only machine-dependent targets (compiled programs and libraries).  Specifying both -prefix and -exec-prefix allows you to segregate machine-dependent files, so that machine-independent files can be shared.

     WARNING: the default BINDEST path prefix in the source is not the same as the prefix for the preconfigured binaries distributed by Cygnus. If you do not use -exec-prefix, the default directory for machine-dependent targets is whatever was specified with -prefix (by default, /usr/local).

-srcdir=PATH
     Warning: This option is only supported if you use GNU make (which is included in the release, except for DOS hosts). Use this option to make configurations in directories separate from the source directories. configure writes configuration specific files in the current directory, but arranges for them to use the source in the directory PATH.  configure will create directories under the working directory in parallel to the source directories below PATH.  Among other things, you can use this to build (or maintain) several configurations simultaneously, in separate directories.

-norecursion
     Configure only the directory level where configure is executed; do not propagate configuration to subdirectories.

-target=TARGET
     Configure the development tools for cross-development (compiling, debugging, or other processing) of programs running on the specified TARGET.  Without this option, programs are configured ``native'', that is, for managing programs that run on the same machine (HOST) as the development tools themselves.

     There is no convenient way to generate a list of all available targets.

HOST ...
     Configure the development tools to run on the specified HOST.

     There is no convenient way to generate a list of all available hosts.

The -prefix=DEST and -exec-prefix=BINDEST options are particularly important.  If you don't specify a DEST or BINDEST directory, the Makefile installs binaries in subdirectories of /usr/local.  These options are important because the DEST and BINDEST directories are used for several purposes:

 1. BINDEST is the directory where binaries are installed.

 2. BINDEST is built into the compiler itself for the locations of GCC specific include files, the locations of GCC subprograms, and the location of the GCC specific library libgcc.a.

 3. DEST is compiled into info as the default directory for the documentation.

Compilation
===========

After you've run configure (which writes the final Makefile in each directory), compilation is straightforward. To compile all the programs in the Developer's Kit, run:

     make all info >make.log

The examples suggest capturing the make output in a make.log file, because the output is lengthy.

The overall Makefile propagates the value of the CC variable explicitly, so that you can easily control the compiler used in this step.  CFLAGS is treated the same way.  For instance, to build the compiler a second time, using GCC to compile itself (after building and installing it in the alternate directory /local/gnu), you might use

     make CC=/local/gnu/H-sun4/bin/gcc CFLAGS=-O all info  >make.log

The conventional targets all, install, and clean are supported at all levels of Makefile.  Other targets are supported as well, as appropriate in each directory; please read the individual Makefile for details.  Each Makefile in the source directories includes ample comments to help you read it.  If you are not familiar with make, refer to Overview of make (GNU Make: A Program for Directing Recompilation).

Installation
============

Whether you configure an alternative path using -prefix, or you use the default installation path /usr/local, you can install the software by executing:

     make install install-info

Known Bugs
**********

Attached at the end of this document is a listing of the known bugs in the Progressive p3-921001 release.  These are organized by software category, for example, g++, or gdb.

Each bug summary begins with the Cygnus PR number and the current state of the problem report.  We consider a problem report closed only when the customer who reported the bug agrees the problem is solved. (Closed bugs are not shown in these summaries.)

The state shown in each problem summary is one of:

open
     We have not yet investigated this bug.

analyzed
     We have examined the situation and diagnosed the problem; a bug fix is pending.

suspended
     We have examined the situation and diagnosed the problem, but determined that a fix cannot currently be applied.

feedback
     We have applied a fix, but have not yet received confirmation from the customer that this solves the problem.  Also indicates bugs awaiting more information from the customer.

Cygnus Releases and the FSF
***************************

Most of the tools in this Developer's Kit are originally from the Free Software Foundation (FSF).  You can get versions of all these tools from the FSF as well as from Cygnus.  In general, Cygnus Progressive Releases add to FSF software in the following ways:

  * Commercial support is available.  Cygnus adds value to FSF releases in large measure by offering outstanding support services.

  * Coordination.  The tools in your Developer's Kit are certified to work together; you need not worry about tools being out of step with each other.

  * Bug fixes.  A Progressive Release includes many fixes, already integrated into the programs.  Cygnus repairs bugs discovered during testing, and also tracks and includes bug fixes developed for other Cygnus customers or distributed over the Internet.

  * Bug reporting.  Cygnus releases include the tool send_pr, which you can use to make sure your problem reports receive prompt attention, and are also incorporated in our future tests.

  * Documentation.  Cygnus revises and adds to available FSF documentation to give you better descriptions of all the software tools.

  * Stability.  Cygnus tests (and uses) all the programs it releases.

About Cygnus Support
********************

Cygnus Support was founded in 1989 to provide commercial support for free software.  Cygnus supplies products and services that benefit advanced development groups by allowing them to use state-of-the-art tools without having to maintain them.  With Cygnus Support, sites that once were forced to do their own tool support can recover that valuable staff time.  Former users of proprietary software now may choose supported free software, combining the advantages of both worlds.

Free software is faster, more powerful, and more portable than its proprietary counterparts.  It evolves faster because users who want to make improvements are free to do so.  Cygnus tracks these improvements and integrates them into tested, stable versions ready for commercial use, then backs this software with comprehensive support.

With Cygnus Support as your partner, you will have the software and the support you need to meet your business objectives.  Cygnus is intimately familiar with this software from extensive experience using, debugging, and implementing it.  You get direct access to the most qualified support people: the authors of the software.

We provide ``vintage'' releases---the most stable versions, which have been though even more extensive use and testing---or up-to-the minute ``progressive'' releases, for those who need the very latest version.

Because all our improvements are also free software, you can distribute them widely within your organization, or to your customers, without extra cost.

     Cygnus Support
     hotline: +1 415 903 1401
     email: info@cygnus.com

     HEADQUARTERS                                    EAST COAST
     1937 Landings Drive                     One Kendall Square
     Mountain View, CA 94043 USA            Cambridge, MA 02139

     +1 415 903 1400                            +1 617 494 1040
     +1 415 903 0122 fax                    fax +1 617 494 1325