$Id$

INTERFACE DEFINITION LANGUAGE COMPILER FRONT END
-==============================================-

INTRODUCTION

Welcome to the publicly available source release of SunSoft's
implementation of the compiler front end (CFE) for OMG Interface Definition
Language! This is Release 1.3 of the CFE.

The Interface Definition Language (IDL) implementation is divided into
three parts:

- A main program for driving the compilation process
- A parser and attendant utilities
- One or more back ends (BEs) for taking the processed input and producing
  output in a target language and target format

WARNINGS

This is a preliminary version. This software is made available AS IS and
WITH NO GUARANTEES. Please read  the copyright notice attached at the
bottom of this file.

IMPORTANT NOTICE FOR USERS OF OMG IDL CFE VERSION 1.2.

Please carefully read the file CHANGES to obtain IMPORTANT INFORMATION on
changes in that may affect the manner in which a BE is constructed. You
must follow instructions contained in the file CHANGES to obtain a
functional BE if you are migrating an existing BE from OMG IDL CFE v. 1.2.

TARGET AUDIENCE

Who should use this release?

- You can use this source release to create a stand alone parser for OMG
  Interface Definition Language. This may be useful to verify the legality
  of IDL input.
- Developers of OMG Interface Definition Language compilers should use this
  release as a basis for writing their back ends, to obtain a common
  framework for their compiler and to provide portable and uniform
  parsing of IDL input.

HOW TO OBTAIN THIS SOFTWARE

Please use anonymous FTP to omg.org and supply your e-mail address as the
password. Then change directories to pub/OMG_IDL_CFE_1.3, set binary transfer
and get the file OMG_IDL_CFE_1.3.TAR.Z. This file includes copies of all
individual documentation files in the directory.

Precompiled binaries constructed from the sources in this release will be
made available shortly, in the directory pub/OMG_IDL_CFE_1.3/bin. These
binaries are useful for parsing IDL source and for learning about the
language. Precompiled binaries for Solaris 2.x and for SunOS 4.x will be
provided.

You can also use the mail server program to retrieve this software. Send
email with the subject 'help' to omg_idl@omg.org, and the mail server will
respond with instructions on how to retrieve the software.

Copies of this software may be made available from archives other than
omg.org. New versions made available by Sun will be placed on omg.org and a
message will be sent to this newsgroup announcing its availability.

Finally, the SunSoft OMG IDL CFE is also available on magnetic tape for a
nominal media charge directly from SunSoft. Please refer to part number
DIDL-100-STP when ordering.

CONTACT POINT

Please let us know who you are if you decide to use this software, and how
you use it. Please send e-mail to:

     idl-cfe@sun.com

This address can also be used to report problems, bugs, suggestions and
send general comments.

WHAT IS PROVIDED IN THE RELEASE

Provided in this release are:

- A main program for driving an Interface Definition Language compiler
- A parser for the Interface Definition Language grammar which builds an
  internal representation of the input parsed. This internal
  representation, named an Abstract Syntax Tree (AST), is used as input to
  a back end
- Some utility functions used by the parser
- A demonstration back end (BE) which exercises the front end but produces
  no translated output
- Documentation of the public interfaces and of the contract between
  the compiler front end and a back end

OPERATION

A complete compiler operates in two passes:

- The first pass, provided in this release, parses the IDL input and
  produces an internal representation, called an Abstract Syntax Tree (AST).
  This pass also does a complete syntax and semantics check of the input
  provided to ensure that exactly legal IDL input is accepted. If a syntax
  or semantic error is discovered, the second pass is not invoked.
- The second pass, provided by compiler developers, takes the AST and
  produces output in the language and format of choice. A demonstration
  back end is provided in the release.

HOW TO USE THIS SOFTWARE

To create a complete compiler from OMG Interface Definition Language to a
target language, compiler developers will:

- Write a back end (BE) to take the internal representation of the input
  parsed and translate it to the target language and format. You will
  probably want to replace the BE directory in this source tree with your
  own BE directory
- Link the BE with the sources provided here to produce a complete
  compiler.

DOCUMENTATION

The OMG Interface Definition Language is fully described in the CORBA
documentation, Chapter 4. This document may be obtained from OMG.

This release also provides the following documents:

- This README file, describing the release
- INSTALL, describing installation of the software
- WRITING_A_BE contains all the information needed to start writing a back
  end for this distribution
- CHANGES_IN_AST describes changes that affect migration of BEs written
  against version 1.2 to version 1.3.
- CLI, describing the command line interface to the CFE
- ROADMAP, describing the directory structure for the source code. This
  file will assist a developer in understanding the structure of the code
  and navigating it
- PROBLEMS, describing a list of issues that may be addressed in future
  releases
- BUG_REPORT, containing a form for use in reporting bugs and problems
  with the IDL CFE

ENVIRONMENT

The INSTALL file explains how to customize the software for specific
platforms. The source distribution expects the following environment:

- Sparcstation 1, 2, or 10 hardware
- SunPro SparcWorks 3.x or 4.0

As preconfigured, it compiles on Solaris 2.x. It can be reconfigured to
compile on SunOS 4.x, HPUX or Apollo Domain OS. As far as is known, no use
is made of Sun Make-specific features, and the Makefiles should be usable
with other make programs.

This release has been tested and is believed to operate correctly with:
- SunPro Sparcworks 2.x and 3.0 on SunOS 4.1.x
- SunPro Sparcworks 2.x and 3.0 on Solaris 2.3
- g++ 2.5.8 on SunOS 4.1.x
- g++ 2.5.8 on Solaris 2.3

INSTALLATION

This release is targetted for Sun workstations running Solaris 2.x. The
process of installing this software is described in detail in the file
INSTALL in this directory. The INSTALL file also describes how to customize
the release for your own environment if it is different.

KNOWN PROBLEMS

A list of known deficiencies is provided in the file PROBLEMS in this
directory. If you find a problem which is not mentioned in it, please
report it as described below. Please read this file now to be apprised of
the problems found so far with this release.

COPYRIGHT

This copyright notice appears on all files. Please read it!

Copyright 1992, 1993, 1994 Sun Microsystems, Inc.  Printed in the United
States of America.  All Rights Reserved.

This product is protected by copyright and distributed under the following
license restricting its use.

The Interface Definition Language Compiler Front End (CFE) is made
available for your use provided that you include this license and copyright
notice on all media and documentation and the software program in which
this product is incorporated in whole or part. You may copy and extend
functionality (but may not remove functionality) of the Interface
Definition Language CFE without charge, but you are not authorized to
license or distribute it to anyone else except as part of a product or
program developed by you or with the express written consent of Sun
Microsystems, Inc. ("Sun").

The names of Sun Microsystems, Inc. and any of its subsidiaries or
affiliates may not be used in advertising or publicity pertaining to
distribution of Interface Definition Language CFE as permitted herein.

This license is effective until terminated by Sun for failure to comply
with this license.  Upon termination, you shall destroy or return all code
and documentation for the Interface Definition Language CFE.

INTERFACE DEFINITION LANGUAGE CFE IS PROVIDED AS IS WITH NO WARRANTIES OF
ANY KIND INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS
FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR ARISING FROM A COURSE OF
DEALING, USAGE OR TRADE PRACTICE.

INTERFACE DEFINITION LANGUAGE CFE IS PROVIDED WITH NO SUPPORT AND WITHOUT
ANY OBLIGATION ON THE PART OF Sun OR ANY OF ITS SUBSIDIARIES OR AFFILIATES
TO ASSIST IN ITS USE, CORRECTION, MODIFICATION OR ENHANCEMENT.

SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES SHALL HAVE NO LIABILITY WITH
RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY
INTERFACE DEFINITION LANGUAGE CFE OR ANY PART THEREOF.

IN NO EVENT WILL SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES BE LIABLE FOR
ANY LOST REVENUE OR PROFITS OR OTHER SPECIAL, INDIRECT AND CONSEQUENTIAL
DAMAGES, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Use, duplication, or disclosure by the government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in
Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR
52.227-19.

Sun, Sun Microsystems and the Sun logo are trademarks or registered
trademarks of Sun Microsystems, Inc.

SunSoft, Inc.
2550 Garcia Avenue
Mountain View, California  94043

NOTE:

SunOS, SunSoft, Sun, Solaris, Sun Microsystems or the Sun logo are
trademarks or registered trademarks of Sun Microsystems, Inc.
