diff options
-rw-r--r-- | TAO/TAO_IDL/docs/ANNOUNCEMENT | 131 | ||||
-rw-r--r-- | TAO/TAO_IDL/docs/BUG_REPORT | 144 | ||||
-rw-r--r-- | TAO/TAO_IDL/docs/CHANGES | 122 | ||||
-rw-r--r-- | TAO/TAO_IDL/docs/CLI | 187 | ||||
-rw-r--r-- | TAO/TAO_IDL/docs/COPYRIGHT | 57 | ||||
-rw-r--r-- | TAO/TAO_IDL/docs/INSTALL | 229 | ||||
-rw-r--r-- | TAO/TAO_IDL/docs/PROBLEMS | 132 | ||||
-rw-r--r-- | TAO/TAO_IDL/docs/README | 233 | ||||
-rw-r--r-- | TAO/TAO_IDL/docs/ROADMAP | 126 | ||||
-rw-r--r-- | TAO/TAO_IDL/docs/WRITING_A_BE | 1350 |
10 files changed, 2711 insertions, 0 deletions
diff --git a/TAO/TAO_IDL/docs/ANNOUNCEMENT b/TAO/TAO_IDL/docs/ANNOUNCEMENT new file mode 100644 index 00000000000..870db6f6006 --- /dev/null +++ b/TAO/TAO_IDL/docs/ANNOUNCEMENT @@ -0,0 +1,131 @@ +WHAT: + +SunSoft, Inc., Mountain View, California, has placed the source code to +Project DOE's Interface Definition Language (IDL) compiler front end +(CFE) on OMG's file server, making the implementation publicly +available. This release is identified by the version number 1.3. + +Project DOE is SunSoft's corporate-wide development effort to integrate +distributed object technology into the Solaris O/S. OMG (Object Management +Group) is the industry wide body formed to create specifications for +distributed object technology. It currently has more than 370 members. OMG +IDL is part of OMG's CORBA 1.1 specification and provides a standardized +way for defining object interfaces. OMG IDL forms the basis for distributed +object interactionin Project DOE. + +The SunSoft OMG IDL CFE provides a complete framework for building +CORBA 1.1-compliant preprocessors for OMG IDL. By using this standard +implementation, developers of OMG IDL compilers will save many months +of work and enhance the portability and interoperability of OMG +IDL-interfaced objects. + +The SunSoft OMG IDL CFE allows convenient and fast integration of new back +ends to the compiler. The release consists of a front end which converts +OMG IDL to an intermediate format, a compiler framework driver, an example +implementation of a compiler back end, and a set of protocols for +interaction between the front and back ends. The SunSoft OMG IDL CFE +parser uses components generated by yacc and lex. + +The SunSoft OMG IDL CFE is designed to allow easy extension of OMG IDL +without impacting existing back-end implementations. As the CORBA +specification evolves, any new updates to the IDE CFE will be placed +by SunSoft on the OMG server. + +This release provides a directory with many examples of OMG IDL +specifications to allow users to become familiar with the process of +writing OMG IDL code. + +For more information send email to idl-cfe@sun.com. + +HOW: + +The SunSoft OMG IDL CFE is available at no charge through anonymous FTP +in source form on the OMG file server, omg.org. Please retrieve the +file OMG_IDL_CFE_1.3.tar.Z from the directory pub/OMG_IDL_CFE_1.3. Please +let us know who you are if you retrieve the compiler front end using this +method, by sending email to idl-cfe@sun.com. + +You can also retrieve the software by using the OMG mail server program. +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. + +WHEN: + +The SunSoft OMG IDL CFE is available now. + +CONTACT: + +Please let us know who you are if you decide to use this software, and how +you use it. Please send email to: + + idl-cfe@sun.com + +This address can also be used to report problems, bugs, suggestions and +send general comments. + +We ask that if you make extensions or modifications to this source release, +please make these extensions available to others using the OMG IDL compiler +front end, by sending the modified sources to the above email address. This +will help us evaluate your extensions for inclusion in a future version. It +also ensures your investment in these extensions when new versions of the +CFE are released. + +NOTE: + +SunOS, SunSoft, Sun, Solaris, Sun Microsystems or the Sun logo are +trademarks or registered trademarks of Sun Microsystems, Inc. + +COPYRIGHT NOTICE: + +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 diff --git a/TAO/TAO_IDL/docs/BUG_REPORT b/TAO/TAO_IDL/docs/BUG_REPORT new file mode 100644 index 00000000000..28c34ae141d --- /dev/null +++ b/TAO/TAO_IDL/docs/BUG_REPORT @@ -0,0 +1,144 @@ +OMG IDL COMPILER FRONT END PROBLEM REPORT FORM +-============================================- + +Checklist: Did you: +- include configuration information? +- include compiler version number (use -V to obtain)? +- include script of run? +- include IDL file causing problem? +- make any changes to the CFE? If so, did you include a diff against + original version? + +PLEASE SEND THE COMPLETED BUG REPORT TO: idl-cfe@sun.com. + +THANK YOU FOR REPORTING THIS PROBLEM! THROUGH YOUR COLLABORATION, SUNSOFT +WILL BE ABLE TO IMPROVE THE FUNCTIONALITY OF THIS PRODUCT. RECEIPT OF BUG +REPORTS WILL BE ACKNOWLEDGED BUT NO OBLIGATION IS UNDERTAKEN BY SUNSOFT TO +CORRECT THE REPORTED PROBLEM. SEE YOUR COPYRIGHT AND LICENSE INFORMATION. + + +CONFIGURATION INFORMATION (describe your hardware platform, operating +system and which compilers you used to compile the CFE): + + + + + + +COMPILER VERSION INFORMATION (include output from idl -V here): + + + + + + + +PROBLEM DESCRIPTION (describe problem, include script if available): + + + + + + + + +IDL INPUT CAUSING PROBLEM (include IDL input causing problem): + + + + + + + + + +DID YOU MAKE ANY CHANGES TO THE CFE? [Y] _ [N] _ +IF YES, INCLUDE A DIF OF YOUR VERSION AGAINST ORIGINAL VERSION: + + + + + + + + + +PROPOSED FIX (if you believe you know the cause of the problem, please +include a proposed change to the software to correct it): + + + + + + + + +ANY OTHER RELEVANT INPUT (include here any other information you believe +may be relevant to the resolution of the problem you described): + + + + + + +PLEASE SEND THIS PROBLEM REPORT TO idl-cfe@sun.com. + +NOTE: + +SunOS, SunSoft, Sun, Solaris, Sun Microsystems or the Sun logo are +trademarks or registered trademarks of Sun Microsystems, Inc. + +COPYRIGHT NOTICE: + +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 diff --git a/TAO/TAO_IDL/docs/CHANGES b/TAO/TAO_IDL/docs/CHANGES new file mode 100644 index 00000000000..ae6fca7bcea --- /dev/null +++ b/TAO/TAO_IDL/docs/CHANGES @@ -0,0 +1,122 @@ +CHANGES WHICH AFFECT BE WRITERS +-=============================- + +INTRODUCTION + +This file describes changes that affect BE writers. It contains IMPORTANT +INFORMATION for BE writers who wish to migrate a BE written to operate with +release 1.2 to operate with release 1.3. It is likely that not following +these instructions will result in a compilable but malfunctioning compiler. + +AST INHERITANCE CHANGES + +The AST has been reorganized so that AST_Union and AST_Exception now +inherit from AST_Structure. This means that constructors of BE classes +which inherit from AST_Union or AST_Exception now need to explicitly call +an initializer for AST_Structure in their init section. + +We repeat below the information given in the file WRITING_A_BE, in the +section entitled "WRITING A BE". + +AST_EXCEPTION + +The signature for constructors of classes inheriting from AST_Exception +should now be: + + BE_Exception::BE_Exception(UTL_ScopedName *n, + UTL_StrList *p) + : AST_Decl(AST_Decl::NT_except, n, p), + AST_Structure(AST_Decl::NT_except, n, p), + UTL_Scope(AST_Decl::NT_except) + +AST_UNION + +The signature for constructors of classes inheriting from AST_Union should +now be: + + BE_Union::BE_Union(AST_ConcreteType *dt, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Union(dt, n, p), + AST_Structure(AST_Decl::NT_union, n, p), + AST_Decl(AST_Decl::NT_union, n, p), + UTL_Scope(AST_Decl::NT_union) + +IDL_BOOL TYPE + +To increase portability and reduce dependency of the sources on POSIX +compliance in targets of ports, IDL now provides its own boolean type which +is named idl_bool. It provides two truth values, I_TRUE and I_FALSE. + +UTL_SCOPEDNAME TYPE + +The UTL_ScopedName type is now a list of Identifier nodes; in previous +releases it used to be a list of String nodes. If your BE constructs scoped +names this change will prevent recompilation until you modify your +constructor calls to invoke constructors for Identifier instead of for +String. The signature of the constructor is: + + Identifier::Identifier(char *, long x=1, long y=0, long z=I_FALSE) + +The additional arguments which can be defaulted to the values indicated are +included for future use. + +COPYRIGHT + +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. diff --git a/TAO/TAO_IDL/docs/CLI b/TAO/TAO_IDL/docs/CLI new file mode 100644 index 00000000000..a61c2bae365 --- /dev/null +++ b/TAO/TAO_IDL/docs/CLI @@ -0,0 +1,187 @@ +OMG INTERFACE DEFINITION LANGUAGE COMPILER FRONT END: COMMAND LINE INTERFACE +-==========================================================================- + +INTRODUCTION + +This document describes general OMG Interface Definition Language compiler +command line options. Options that are specific to a given back end, object +adapter or language are not described here. These should be described in a +document detailing the interface implemented by each specific back end. + +OMG INTERFACE DEFINITION LANGUAGE COMMAND LINE OPTIONS + +OMG Interface Definition Language compiler options are described below. +Unless otherwise noted, only one occurrence of each option is allowed. +The following conventions are used + +- Text in '[..]' is optional. +- Text followed by '*' can be repeated zero or more times. +- Text followed by '+' can be repeated once or more times. +- '{' and '}' are used to group text to cause '+' or '*' to apply to + the entire grouped text. +- 'aa|bb' means either 'aa' or 'bb'. + +COMMAND LINE SUMMARY + + idl [flag | file-name]* + +Flags are command line words that start with a '-'. All other command line +words are assumed to be file names. If no file names are given, input is +taken from stdin. + +COMMAND LINE FLAGS + +-A[xyz] A local escape. This can be used to specify additional options that + are specific to a given implementation. More than one -A option is + allowed + +-Dname[=value] + Defines name and an optional value to be passed to a compliant C++ + preprocessor, as if by #define. White space between the -D option + and the name is optional. More than one -D option is allowed. + +-d If no parse errors were found, prints out a representation of the + IDL input to stderr. + +-E Runs the C++ preprocessor on the OMG Interface Definition Language + input and sends the result to the standard output. + +-Idirectory + Causes directory to be added to the search path for include files. + More than one -I option is allowed. This option is processed by a + compliant C++ preprocessor. + +-Uname Undefines name, as if by #undef. White space between the -U option + and the name is optional. More than one -U option is allowed. + +-V Causes the version information of the CFE to be displayed. No other + work is done, regardless of any other options. + +-W[b|p][,arg]+ + Hands off the arguments supplied to a specific portion of the OMG + Interface Definition Language compiler: + + - -Wb arguments are handed to the loaded back end + - -Wp arguments are handed to a compliant C++ preprocessor + +-Yp,pathname + Specifies an alternate path for finding a C++ compliant + preprocessor. Specifiers other than 'p' may be defined in future + versions of the CFE. More than one -Y option may appear. The last + one specifying each component takes effect. + + This option exists but currently does nothing. Instead, we use the + preprocessing facilities provided by invoking CC -E always. + +-bback_end + Causes the CFE to use a different compiler back end than the + default one (if dynamic loading is supported). Legal values for + this option and the default value are implementation specific. + +-u Prints a usage message from the CFE. All possible options are + shown. No other work is done regardless of any other options. + +-v Causes the CFE to produce informational output as the various + phases of the compiler execute. + +-w Suppresses IDL compiler warning messages. + + +WHITESPACE + +All option arguments may be separated from their option letter by +whitespace. For example, -D FOO is equivalent to -DFOO. + +UNKNOWN OPTIONS + +If an unknown option is passed to the CFE, the offending option is +displayed to the user together with a usage message, and no compilation is +performed. + +PASSING OPTIONS TO COMPILER PHASES + +The order in which options appear on the command line is preserved when +they are passed to various compiler phases. + +MUTUALLY EXCLUSIVE OPTION COMBINATIONS + +Mutually exclusive or ambiguous option combinations are resolved by using +the option that appears later on the command line. For example, + + -DFOO -UFOO + +has no effect and leaves FOO undefined for the preprocessor. + +OPTION SCOPE + +All options are in effect for the entire IDL compilation run. If multiple +IDL source file names are given on the command line, all options apply to +each file. If different IDL source files require different sets of options +for successfull compilation, they must be compiled separately. + +EXIT STATUS + +IDL Compilers exit with status equal to zero for successfull compilations. +If errors were found by the CFE, the exit status is a count of the errors. +The exit status for unsuccessfull compilations aborted by BEs is defined by +each BE. + +NOTE: + +SunOS, SunSoft, Sun, Solaris, Sun Microsystems or the Sun logo are +trademarks or registered trademarks of Sun Microsystems, Inc. + +COPYRIGHT NOTICE: + +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 diff --git a/TAO/TAO_IDL/docs/COPYRIGHT b/TAO/TAO_IDL/docs/COPYRIGHT new file mode 100644 index 00000000000..461ad949518 --- /dev/null +++ b/TAO/TAO_IDL/docs/COPYRIGHT @@ -0,0 +1,57 @@ +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. diff --git a/TAO/TAO_IDL/docs/INSTALL b/TAO/TAO_IDL/docs/INSTALL new file mode 100644 index 00000000000..6fcaa710042 --- /dev/null +++ b/TAO/TAO_IDL/docs/INSTALL @@ -0,0 +1,229 @@ +INTERFACE DEFINITION LANGUAGE INSTALLATION GUIDE +-==============================================- + +INTRODUCTION + +This file describes the installation process for OMG_IDL_CFE version 1.3. +This file explains how to: + +- install the source code +- modify the sources to customize them for different configurations +- modify the sources to implement your own back end + +TESTED CONFIGURATIONS + +This release has been tested and is believed to operate correctly on: +- 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 + +This is the first release of OMG IDL CFE which is preconfigured to compile +correctly for Solaris 2.x and with SunPro SparcWorks compilers. + +CUSTOMIZATION + +The release contains a file idl_make_vars in the current directory, which +is included in each Makefile. This file defines all the customizable +variables for the CFE. + +OSV should be set to a string denoting the operating system upon which you +wish to build the CFE. The CFE as shipped is preconfigured to compile +correctly on Solaris 2.x (OSV=SOLARIS2), and has also been tested on SunOS +4.1.x (OSV=SUNOS4). It contains code donated by HP which enables it to be +compiled on Apollo Domain systems (OSV=apollo) and HPUX systems (OSV=hpux), +but these two configurations have not been tested. + +C++ and CCC should be set to identify the C++ compiler you will use to +compile this release. Their values should be identical. Both are set to +address differences between various make programs - some predefine CCC, +others use C++ to denote the C++ compiler. The possible values are CC +(which uses the Sparcworks compilers on SunOS 4.1 and Solaris 2.3) and g++, +which uses the installed version of GNU C++. + +CCFLAGS should be set to a list of flags to pass to the C++ compiler. As +shipped, this list is -g. NOTE: We have not extensively tested the release +with optimization turned on. + +CPP_FLAGS should be set to a list of flags to pass to the C++ preprocessor. +Use this variable to enable or disable specific customizations you make to +the BE or CFE sources. + +YFLAGS should be set to a list of flags to pass to the Yacc program. As +shipped, the list is -d -t, which causes Yacc to generate y.tab.h and +y.tab.c files. + +LEXFLAGS should be set to a list of flags to pass to the Lex program. As +shipped, the list -t. + +RANLIB should be set to the location of the ranlib program on your system. +As shipped this is ranlib. If your system has no ranlib you can set this +variable to ':' or /bin/true. As shipped the variable is preset to +/bin/true since Solaris 2.x does not use ranlib. + +AR should be set to the location of the ar program on your system. As +shipped this is ar. If your system has a different mechanism for creating +libraries, you should modify the value of this variable accordingly. + +ARFLAGS should be set to the flags to be passed to the ar program. As +shipped this is 'crv'. + +INSTALLATION + +a. Disk space requirements + +This distribution requires approximately 350 KBytes when compressed. When +uncompressed, untarred and compiled, approximately 10 MBytes of disk space +are consumed on a Sun 4. + +b. Getting the software + +Use anonymous FTP to omg.org and supply your e-mail address as password. +Change directories to pub/OMG_IDL_CFE_1.3, set bin and get the compressed +tar file OMG_IDL_CFE_1.3.tar.Z. + +The distribution may, in the future, be made available from other archives +on the Internet. However, omg.org will always have the most up-to-date +version of this software. + +After transferring this file, uncompress it and untar it in a directory of +your choice. + +c. Compiling it + +If you are using a Sparcstation running Solaris 2.x and have the SunPro +Sparcworks compilers installed, you may directly install the software. If +your hardware or operating system configurations are different, read and +follow the instructions in the previous section first. + +At the root directory of the release, issue + + % make + +or + + % make all + +This will compile the provided sources and the sources found in the be +directory. Executing this make target causes 'make all' to be invoked in +each subdirectory, resulting in building the libraries for each component +and finally a link step producing an executable IDL compiler. + +In order to make only the compiler front end components, without compiling +the sources found in the be directory and without building an executable, +issue + + % make libs + +This will build the libraries in the ast, fe, util, driver and narrow +directories. To build only the be, issue + + % make be + +To build all libraries without creating an executable, issue + + % make all_libs + +To remove all files created by the build process, issue + + % make clean + +This will not remove any files created by Yacc and Lex, because you may be +using the ones provided in the distribution (see below). + +d. Yacc and Lex + +Some installations may not have a C++ aware Yacc and Lex processor. For +these installations, we have included the output of yacc and lex in the +release. If you need to use these files to build the release because you +don't have access to a C++ capable Yacc or Lex, go to the "fe" directory, +issue the command: + + % touch lex.yy.cc y.tab.cc y.tab.hh + +This will ensure that the processed files appear to be newer than the +source files they were produced from and will cause "make" to skip their +production. + +NOTE: The files provided in the distribution have been produced on Solaris +2.3 and may contain OS-specific #include directives. If you intend to use +these files, you may have to edit them to make them work in your +environment. The provided files are known to compile cleanly without +modification with both SunPro Sparcworks compilers and GNU C++ on both +SunOS 4.1 and Solaris 2.3. We have not tested the grammar and lexer input +files with bison or flex. + +IMPLEMENTING A BACK END + +To implement your own back end, you can start with the provided sources in +the be directory and modify them. The Makefile understands the 'make all' +target and will generate libbe.a in the demo_be directory. As set up, the +variable CPP_FLAGS allows you to place include files either in the current +directory or in the include directory. Alternatively, you can place your +include files in a new directory and modify CPP_FLAGS to cause the C++ +preprocessor to search this new directory for referenced include files, by +adding a new -I directive. + +Additional detail on the structure and function of back ends, and on the +protocol which a back end must implement, are found in the document +entitled WRITING_A_BE. + +COPYRIGHT + +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. diff --git a/TAO/TAO_IDL/docs/PROBLEMS b/TAO/TAO_IDL/docs/PROBLEMS new file mode 100644 index 00000000000..65cfb6a1893 --- /dev/null +++ b/TAO/TAO_IDL/docs/PROBLEMS @@ -0,0 +1,132 @@ +OMG INTERFACE DEFINITION LANGUAGE COMPILER FRONT END: KNOWN PROBLEMS +-==================================================================- + +INTRODUCTION + +This file describes what configurations are known to work correctly with +this release, and what are the known problems with this release as shipped. +Comments about future possible enhancements do not imply a commitment on +the part of Sun or any of its subsidiaries to produce these enhancements. + +TESTED CONFIGURATIONS + +This release has been tested and is known to operate correctly on: + +- Sparcstation 2 running SunOS 4.1.2, when compiled with SparcWorks 3.0 +- Sparcstation 10 running Solaris 2.3, when compiled with SparcWorks 3.0.1 +- Sparcstation 10 running Solaris 2.3, when compiled with SparcWorks 4.0 + +We are aware of a bug in GNU C++ (the latest version we tested was 2.5) +which causes up-casting (changing the type of an instance from a base class +to a more derived class, also known as "narrowing") to fail or cause a +program crash. + +PROBLEMS: + +This is a list of known problems with the current version of the CFE: + +- The following syntax, although legal, is not accepted by the CFE: + + .. sequence <string <10>> .. + + This causes a parse error. The cause of this problem is that the '>>' is + read as a right shif operater and not as two '>'s. You can avoid this + problem by instead writing + + .. sequence <string <10> > .. + +- The following syntax, although legal, is not accepted by the CFE: + + const string foo = "abc" " and" " another" " string"; + + Instead, write: + + const string foo = "abc and another string"; + +- The printout produced by the -d option for dumping the AST is not always + perfect. Specifically, dumping of sequences and arrays is deficient. + +POSSIBLE FUTURE ENHANCEMENTS: + +This is a list of areas in which the code of the CFE may change in future +releases: + +- The current release is restricted in its use of C++ because it must + be possible to compile it using C++ 2.1. However, we have also provided + files that depend on features which are only present in C++ 3.0, such as + templates. If your compiler supports templates and you wish to use them, + copy the files in include/utl_tmpl to include, and copy the files in + util/utl_tmpl to util. You will also need to make compiler dependent + modifications to Makefiles throughout the CFE directory hierarchy to + enable the use of templates. + + The code using templates was donated by Steve Vinoski of HP. + + In a future release of the CFE only the template code may be included, + and hence users will need to use a C++ 3.0 or higher compiler. + +- The UTL_list classes defined in the util directory are rudimentary. More + features may be added to make the functionality richer. + +- The UTL_String class may be rewritten or replaced by a standard ANSI C++ + String implementation. Applications will be shielded from this change. + +COPYRIGHT: + +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. diff --git a/TAO/TAO_IDL/docs/README b/TAO/TAO_IDL/docs/README new file mode 100644 index 00000000000..6d73554acce --- /dev/null +++ b/TAO/TAO_IDL/docs/README @@ -0,0 +1,233 @@ +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. diff --git a/TAO/TAO_IDL/docs/ROADMAP b/TAO/TAO_IDL/docs/ROADMAP new file mode 100644 index 00000000000..5da0d83823c --- /dev/null +++ b/TAO/TAO_IDL/docs/ROADMAP @@ -0,0 +1,126 @@ +INTERFACE DEFINITION LANGUAGE SOURCE TREE ROADMAP +-===============================================- + +INTRODUCTION + +This file provides an overview of the directory structure of the sources +for the compiler front end for OMG Interface Definition Language. This will +be of use in understanding the source structure and will aid developers of +BEs. + +DIRECTORIES + +The following directories are present: + +- idl_specs: Contains many examples of IDL specifications, including the + IDL specifications of several Object Services, and several + files that somewhat exhaustively test features of the IDL + language +- include: Contains all include (".hh") files +- ast: Contains implementations for all classes comprising + the AST internal representation of the input parsed +- fe: Contains the Yacc grammar and Lex specification for + the OMG Interface Definition Language, and some utilities +- driver: Contains the main program which drives the compilation + process +- util: Contains utility classes used throughout the CFE. These + classes may also be of use in writing a BE +- narrow: Contains an implementation of a narrowing mechanism used + in the CFE. Since C++ does not provide compiler support + for narrowing, this is provided as an explicit service +- demo_be: Contains a demonstration back end which subclasses all + the AST classes but adds no functionality + +NAMING CONVENTIONS + +The file names start with two or three characters identifying the component +to which they belong: + +- idl_: This is the prefix for all files which contain global + elements of the CFE +- ast_: This is the prefix for all files containing implementations + or definitions of the AST +- fe_: This is the prefix for all files belonging to the parser +- drv_: This is the prefix for all files belonging to the compiler + driver +- utl_: This prefix is used to identify files belonging to the set of + utlities provided with the CFE +- nr_: This prefix identifies files belonging to the narrowing mechanim +- be_: This is the prefix for all files belonging to the back end + +All C++ files use the ".cc" extension, and all include files have the ".hh" +extension. All make files are named Makefile. Each directory contains a +make file. Lex input files have the ".ll" extension, and Yacc input files +use the ".yy" extension. All files containing IDL specifications have a +name ending with the ".idl" suffix. + +INCLUDE FILE HIERARCHY + +There are two main include files which must be included in all source +files. These are idl.hh and idl_extern.hh. The idl.hh file includes the +definitions for all the facilities provided by the CFE. The idl_extern.hh +file declares globally accessible data and exported application programmer +interface entry points. + +Each component has an include file for its own. Back end writers will want +to modify be.hh and possibly be_extern.hh. + +COPYRIGHT + +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. diff --git a/TAO/TAO_IDL/docs/WRITING_A_BE b/TAO/TAO_IDL/docs/WRITING_A_BE new file mode 100644 index 00000000000..cc3bd0a8e35 --- /dev/null +++ b/TAO/TAO_IDL/docs/WRITING_A_BE @@ -0,0 +1,1350 @@ +OMG INTERFACE DEFINITION LANGUAGE COMPILER FRONT END PROTOCOLS +============================================================== + +INTRODUCTION +------------ + +Welcome to the publicly available source release of SunSoft's +implementation of the compiler front end (CFE) for OMG Interface Definition +Language! + +This document explains how to use the release to create a fully functional +OMG Interface Definition Language to target language compiler for your +selected target system configuration. The section OVERVIEW explains this +document's structure. + +CONTEXT +------- + +The implementation has three parts: + +1. A main program driving the compilation process +2. A parser and attendant utilities for converting the IDL input into + an internal form +3. One or more back ends which take as input the internal form representing + the IDL input, and which produce output in a target language and target + format + +The release contains components 1 and 2, and a demonstration implementation +of component 3. To use this release, you + +- write a back end which takes the internal representation of the parsed input + and translates it to the target language and format. You may replace or + modify the demonstration back end provided. +- link the back end with the provided main program and parser sources + to produce a complete compiler. + +OVERVIEW +-------- + +This document does not explain IDL nor does it introduce IDL features. +For this information, refer to the OMG CORBA specification, available by +anonymous FTP from omg.org. + +This document does not explain C++, except to demonstrate how it is +used to construct the CFE. The ARM by Stroustrup and Ellis provides a +thorough explanation of C++. + +This document consists of two independent parts. The first part +describes all CFE supported protocols and the required +application programmer's interface entry points that a conformant +BE must provide. The second part steps through the process of +constructing a working BE. + +The first part describes: + +- The compilation process +- The Abstract Syntax Tree (AST) internal representation of parsed IDL + input +- How access to member data fields is managed +- How the AST is generated from the IDL input (Generator protocol) +- How definition scopes are nested and how name lookup works +- The narrowing mechanism +- How definition scopes are managed and how nodes are added to scopes +- How BEs get control during the AST construction process (Add protocol) +- The inheritance scheme used by the AST and how it affects BEs +- How errors are handled and reported +- How the CFE is initialized +- How the command line arguments are parsed +- What global variables and functions are provided +- What API is required to be supported by a BE in order to link + with the CFE +- What files must be included in each BE file + +The second part describes + +- The API to be supplied by each BE +- How to subclass from the AST to add BE specific functionality +- How to subclass from the Generator protocol to create BE specific + extended AST nodes +- How to write constructors for the derived BE classes +- How to use the Add protocol to store BE specific information +- How to maintain BE specific information which applies to the entire + AST generated from the IDL input +- How to use data members in your BE +- How to build a complete compiler + +PART I. FEATURES OF THE CFE +-=========================- + +THE COMPILATION PROCESS +----------------------- + +The OMG IDL compiler operates as follows: + +- Parses command line arguments. If an option is directed at a + BE, an appropriate operation provided by the BE is invoked to process + the option. +- Performs global initialization. +- Forks a copy of the compiler for each file specified as input. +- An ANSI-compatible preprocessor preprocesses the IDL input. +- Parses the file using the CFE parser, and constructs an AST describing the + IDL input. +- Prints the AST for verification, if requested. +- Invokes the BE to process the AST and produce the output + characteristic of that BE. + +ABSTRACT SYNTAX TREE +-------------------- + +The AST (Abstract Syntax Tree) is the primary mechanism for communication +between a BE and the CFE. It consists of a tree of instances of classes +defined in the CFE or refinements of those classes as defined in a BE. +The class hierarchy of the AST closely resembles the structure of the IDL +syntax. Most AST classes have direct equivalents in IDL constructs. + +The UTL_Scope class defines common functionality for definition scope +management and name lookup. This is explained in a following section. +UTL_Scope is defined in include/utl_scope.hh and implemented in +util/utl_scope.cc. + +The AST provides the following classes: + +AST_Decl Base of the AST class hierarchy. Each class in the AST + inherits from AST_Decl. Defined in include/ast_decl.hh + and implemented in ast/ast_decl.cc + +AST_Type Common base class for all classes which represent IDL + type constructs. Defined in include/ast_type.hh and + implemented in ast/ast_type.cc. Inherits from AST_Decl. + +AST_ConcreteType Common base class for all classes which represent IDL + types other than interfaces. Defined in the file + include/ast_concrete_type.hh and implemented in + ast/ast_concrete_type.cc. Inherits from AST_Type. + +AST_PredefinedType Instances of this class represent all predefined types + such as long, char and so forth. Defined in the file + include/ast_predefined_type.hh and implemented in + ast/ast_predefined_type.cc. Inherits from + AST_ConcreteType. + +AST_Module Represents the IDL module construct. Defined in the + file include/ast_module.hh and implemented in + ast/ast_module.cc. Inherits from AST_Decl and + UTL_Scope. + +AST_Root Represents the root of the abstract syntax tree being + constructed. Is a subclass of AST_Module. Can be + subclassed in BEs to store information associated with + the entire AST. Defined in the file include/ast_root.hh + and implemented in ast/ast_root.cc. Inherits from + AST_Module. + +AST_Interface Represents the IDL interface construct. Defined in + include/ast_interface.hh and implemented in the file + ast/ast_interface.cc. Inherits from AST_Type and + UTL_Scope. + +AST_InterfaceFwd Represents a forward declaration of an IDL interface. + Defined in include/ast_interface_fwd.hh and implemented + in ast/ast_interface_fwd.cc. Inherits from AST_Decl. + +AST_Attribute Represents an IDL attribute construct. Defined in + include/ast_attribute.hh and implemented in the file + ast/ast_attribute.cc. Inherits from AST_Decl. + +AST_Exception Represents an IDL exception construct. Defined in + include/ast_exception.hh and implemented in the file + ast/ast_exception.cc. Inherits from AST_Decl. + +AST_Structure Represents an IDL struct construct. Defined in the file + include/ast_structure.hh and implemented in the file + ast/ast_structure.cc. Inherits from AST_ConcreteType + and UTL_Scope. + +AST_Field Represents a field in an IDL struct or exception + construct. Defined in include/ast_field.hh and + implemented in ast/ast_field.cc. Inherits from + AST_Decl. + +AST_Operation Represents an IDL operation construct. Defined in the + file include/ast_operation.hh and implemented in + ast/ast_operation.cc. Inherits from AST_Decl and + UTL_Scope. + +AST_Argument Represents an argument to an IDL operation construct. + Defined in include/ast_argument.hh and implemented in + ast/ast_argument.cc. Inherits from AST_Field. + +AST_Union Represents an IDL union construct. Defined in + include/ast_union.hh and implemented in + ast/ast_union.cc. Inherits from AST_ConcreteType and + from UTL_Scope. + +AST_UnionBranch Represents an individual branch in an IDL union + construct. Defined in include/ast_union_branch.hh and + implemented in ast/ast_union_branch.cc. Inherits from + AST_Field. + +AST_UnionLabel Represents the label of an individual branch in an IDL + union construct. Defined in include/ast_union_label.hh + and implemented in ast/ast_union_label.cc + +AST_Constant Represents an IDL constant construct. Defined in + include/ast_constant.hh and implemented in the file + ast/ast_constant.cc. Inherits from AST_Decl. + +AST_Enum Represents an IDL enum construct. Defined in the file + include/ast_enum.hh and implemented in ast/ast_enum.cc. + Inherits from AST_ConcreteType and UTL_Scope. + +AST_EnumVal Represents an enumerator in an IDL enum construct. + Defined in include/ast_enum_val.hh and implemented in + ast/ast_enum_val.cc. Inherits from AST_Constant. + +AST_Sequence Represents an IDL sequence construct. Defined in + include/ast_sequence.hh and implemented in + ast/ast_sequence.cc. Inherits from AST_Decl. + +AST_String Represents an IDL string construct. Defined in the file + include/ast_string.hh and implemented in + ast/ast_string.cc. Inherits from AST_Decl. + +AST_Array Represents an array modifier to the type of an IDL + field or typedef declaration. Defined in the file + include/ast_array.hh and implemented in + ast/ast_array.cc. Inherits from AST_Decl. + +AST_Typedef Represents an IDL typedef construct. Defined in the file + include/ast_typedef.hh and implemented in + ast/ast_typedef.cc. Inherits from AST_Decl. + +AST_Expression Represents an IDL expression. Defined in the file + include/ast_expression.hh and implemented in + ast/ast_expression.cc. + +AST_Root A subclass of AST_Module, an instance of this class + is used to represent the distinguished root node of + the AST. Defined in include/ast_root.hh and implemented + in ast/ast_root.cc. Inherits from AST_Module. + + +USING INSTANCE DATA +------------------- + +The AST classes define member data fields in addition to defining +operations on instances. These member data fields are all private, to allow +only the instance in which they are stored direct access. Other objects +(including other instances of the same class) can obtain access to the +member data fields of an instance through accessor functions. These +accessor functions allow retrieval of the data, and in some cases update +functions are also provided to store new values. + +There are several reasons why this approach is taken. First, it hides the +actual implementation of the member data fields from outside the class. For +example, a Thermometer class would not expose whether its temperature +reading is stored in Farenheit or Celsius units, and it could allow access +through either unit method. + +Second, protecting access to member data in this manner restricts the +ability to update it to the instance itself, save where update functions +are explicitly provided. This makes for more reliable implementations, +since the manipulation of the data is isolated in the class implementation +itself. + +Third, wrapping a function call around access to member data allows such +access and update operations to be protected in a multithreaded +environment. While the CFE itself is not multithreaded and the access +operations as currently defined do no special work to protect against +mutliple conflicting access operations, this may be changed in a future +version. Moving the CFE to a multithreaded environment without protecting +access to member data in this manner would be extremely difficult. + +The protocol defined in the CFE is that member data fields are all private +and have names which start with the prefix "pd_" (denoting Private Data). +The access functions have names which are the same as the name of the field +sans the prefix. For example, AST_Decl has a field pd_defined_in and an +access function defined_in(). + +The update functions have names starting with "set_" followed by the name +of the corresponding access function. Thus, AST_Decl defines a function +set_in_main_file(boolean) which sets the pd_in_main_file data member's +value to the boolean provided. + +GENERATION OF THE AST +--------------------- + +The CFE generates the abstract syntax tree after parsing IDL +input. The nodes of the AST are defined by classes introduced in the +previous section, or by subclasses thereof as defined by each BE. In +writing the CFE, we were faced with the following problem: how to generate +the AST containing nodes of the derived classes as defined in each BE +without knowledge of the types and conventions of these BE classes. + +One alternative was to define a naming scheme which predetermines the names +of each subclass a BE can define. The AST would then be generated by +calling an appropriate constructor on the BE derived class. This scheme +suffers from some shortcomings: + +- It breaks the modularity of the compiler and imports knowledge about + types defined in a BE into the CFE, where this information does not belong. +- It restricts a compiler to having only one BE loaded at a time because the + names of these classes can be in use in only one BE at a time. +- It requires a BE to provide derived classes for all AST classes, even for + those classes where the BE adds no functionality. + +The mechanism we chose is different. We define the AST_Generator class +which has an operation for each constructor defined on each AST class. The +operation takes arguments appropriate to the constructor, invokes it and +returns the created AST node, using the type known to the CFE. All such +operations on the generator are declared virtual. The names of all +operations start with "create_" and contain the name of the construct. +Thus, an operation which invokes a constructor of an AST_Module is named +create_module. AST_Generator is defined in include/ast_generator.hh and +implemented in ast/ast_generator.cc. + +If a BE derives from any AST class, it must also derive from the +AST_Generator class and redefine the relevant operations to invoke +constructors of the BE provided class instead of the AST provided class. +For example, if BE_Module is a subclass of AST_Module in a BE, the BE would +also define BE_Generator and redefine create_module to call the constructor +of BE_Module instead of that provided by AST_Module. + +During initialization, the CFE causes an instance of the BE derived +generator to be created and saved. This is explained in the section on +REQUIRED ENTRY POINTS SUPPLIED BY A BE. During parsing, actions in the Yacc +grammar invoke operations on the saved instance to create new nodes for the +AST as it is being built. These operations invoke constructors for BE +derived classes or for AST provided classes if they were not overridden. + +DEFINITION SCOPES +----------------- + +IDL is a nested scoped language. The scoping rules are defined by the CORBA +spec and closely follow those of C++. + +Scope management is implemented in two classes provided in the utilities +library, UTL_Scope and UTL_Stack. UTL_Scope manages associations between +names and AST nodes, and UTL_Stack manages scope nesting and entry and exit +from definition scopes as the parse is proceeding. UTL_Scope is defined in +include/utl_scope.hh and implemented in util/utl_scope.cc. UTL_Stack is +defined in include/utl_stack.hh and implemented in util/utl_stack.cc. + +During initialization, the CFE creates an instance of UTL_Stack and saves +it. During parsing, as definition scopes are entered and exited, AST nodes +are pushed onto, or popped from, the stack represented by the saved +instances. Nodes on the stack are stored as instances of UTL_Scope. Section +THE NARROWING MECHANISM explains how to obtain the real type of a node +retrieved from the stack. + +All definition scopes are linked in a tree rooted in the distinguished AST +root node. This linkage is implemented by UTL_Scope and AST_Decl. The +linkage is a permanent record of the scope nesting while the stack is a +dynamic record which at each instant represents the current state of the +parse. + +The nesting information is used to do name lookup. IDL uses scoped names +which are concatenations of definition scope names ending with individual +construct names. For example, in + + interface a { + struct b { + long c; + }; + const long k = 23; + struct s { + long ar[k]; + }; + }; + +the name a::b::c represents the long field in the struct b inside the +interface a. + +Lookup is performed by searching down the linkage chain for the first component +of the name, then, when found, recursively resolving the remaining +components in the scope defined by the first component. Lookup is relative +to the scope of use; in the above example, k could also have been referred to +as a::k within the struct s. + +Nodes are stored in a definition scope as instances of AST_Decl. Thus, name +lookup returns instances of AST_Decl. The next section, THE NARROWING +MECHANISM, explains how to obtain the real type of a node retrieved from a +definition scope. + +THE NARROWING MECHANISM +----------------------- + +Here we give only a cursory explanation of how narrowing works. We +concentrate on defining the problem and showing how to use our narrowing +mechanism. The narrowing mechanism is defined in include/idl_narrow.hh. + +As explained above, nodes are stored on the scope stack as instances of +UTL_Scope, and inside definition scopes as instances of AST_Decl. Also, +nodes are linked in a nesting tree as instances of AST_Decl. Given a node +retrieved from the stack or a definition scope, one is faced with the task +of obtaining its real class. C++ does not currently provide an implicit +mechanism for narrowing to a derived class, so the CFE defines its own +mechanism. This mechanism requires some work on your part as BE implementor +and requires some explicit code to be written when it is to be used. + +The class AST_Decl defines an enum whose members encode specific AST node +classes. AST_Decl provides an accessor function, node_type(), which +retrieves a member of the enum representing the AST type of the node. Thus, +if an instance of AST_Decl really is an instance of AST_Module, the +node_type() accessor returns AST_Decl::NT_module. + +The class UTL_Scope also provides an accessor function, scope_node_type(), +which returns a member of the enum encoding the actual type of the node. +Thus, given an UTL_Scope instance which is really an instance of +AST_Operation, scope_node_type() would return AST_Decl::NT_op. + +Perusing the header files for classes provided by the AST, you will note +the use of some macros defined in include/idl_narrow.hh. These macros +define the explicit narrowing mechanism: + +DEF_NARROW_METHODSx(<class name>,<parent_x>) for x equal to 0,1,2 or 3, +defines a narrowing method for the specified class which has 0,1,2 or 3 +immediate base classes from which it inherits. For example, ast_module.hh +which defines AST_Module contains the following line: + + DEF_NARROW_METHODS2(AST_Module, AST_Decl, UTL_Scope) + +This is because AST_Module inherits directly from AST_Decl and UTL_Scope. + +DEF_NARROW_FROM_DECL(<class name>) appears in class definitions for classes +which are derived from AST_Decl and which can be stored in a definition +scope. This macro declares a static operation narrow_from_decl(AST_Decl *) +on the class in which it appears. The operation returns the provided +instance as an instance of <class name> if it can be narrowed, or NULL. + +DEF_NARROW_FROM_SCOPE(<class name>) appears in class definitions of classes +which are derived from UTL_Scope and which can be stored on the scope +stack. This macro declares a static operation narrow_from_scope(UTL_Scope *) +on the class in which it appears. The operation returns the provided +instance as an instance of <class name> if it can be narrowed, or NULL. + +Now look in the files implementing these classes. You will note occurrences +of the following macros: + +IMPL_NARROW_METHODSx(<class name>,<parent_x>) for x equal to 0,1,2 or 3, +implements a narrowing method for the specified class which has 0,1,2 or 3 +immediate base classes from which it inherits. For example, ast_module.cc +which implements AST_Module contains the following line: + + IMPL_NARROW_METHODS2(AST_Module, AST_Decl, UTL_Scope) + +IMPL_NARROW_FROM_DECL(<class name>) implements a method to narrow from an +instance of AST_Decl to an instance of <class name> as defined above. + +IMPL_NARROW_FROM_SCOPE(<class name>) implements a method to narrow from an +instance of UTL_Scope to an instance of <class name> as defined above. + +To put it all together: In the file ast_module.hh, you will find: + + // Narrowing + DEF_NARROW_METHODS2(AST_Module, AST_Decl, UTL_Scope); + DEF_NARROW_FROM_DECL(AST_Module); + DEF_NARROW_FROM_SCOPE(AST_Module); + +In the file ast_module.cc, you will see: + +/* + * Narrowing methods + */ +IMPL_NARROW_METHODS2(AST_Module, AST_Decl, UTL_Scope) +IMPL_NARROW_FROM_DECL(AST_Module) +IMPL_NARROW_FROM_SCOPE(AST_Module) + +The CFE uses narrowing internally to obtain the correct type of nodes in +the AST. The CFE contains many code fragments such as the following: + + AST_Decl *d = get_an_AST_Decl_from_somewhere(); + AST_Module *m; + ... + if (d->node_type() == AST_Decl::NT_module) { + m = AST_Module::narrow(d); + if (m == NULL) { // Narrow failed + ... + } else { // Success, do normal processing + ... + } + } + ... + +Similar code implements narrowing instances of UTL_Scope to their actual +types. + +In your BE classes which derive from UTL_Scope you must include a line +defining how to narrow from a scope, so: + + DEF_NARROW_FROM_SCOPE(<your BE class>) + +and similarly for your BE classes which derive from AST_Decl. + +The narrowing mechanism is defined only for narrowing from AST_Decl and +UTL_Scope. If your BE class inherits directly from one or more classes +which themselves are derived from AST_Decl and/or UTL_Scope, you must +include a line + + DEF_NARROW_METHODSx(<your class name>,<parent 1>,<parent 2>) + +To make this concrete, here is what you'd write in a definition of BE_union +which inherits from AST_Union: + + DEF_NARROW_METHODS1(BE_Union, AST_Union); + DEF_NARROW_FROM_DECL(BE_Union); + DEF_NARROW_FROM_SCOPE(BE_Union); + +and in the implementation file of BE_Union: + +/* + * Narrowing methods: + */ +IMPL_NARROW_METHODS1(BE_Union, AST_Union) +IMPL_NARROW_FROM_DECL(BE_Union) +IMPL_NARROW_FROM_SCOPE(BE_Union) + +Then, in BE code which expects to see an instance of your derived BE_Union +class, you will write: + + AST_Decl *d = get_an_AST_Decl_from_somewhere(); + BE_Union *u; + ... + if (d->node_type() == AST_Decl::NT_union) { + u = BE_Union::narrow_from_decl(d); + if (u == NULL) { // Narrow failed + ... + } else { // Success, do normal processing + ... + } + } + ... + + +SCOPE MANAGEMENT +---------------- + +Instances of classes which are derived from UTL_Scope implement definition +scopes. A definition scope can contain any kind of AST node as long as it +is derived from AST_Decl. However, specific kinds of definition scopes such +as interfaces and unions can contain only a restricted subset of all AST +node types. + +UTL_Scope provides operations to add instances of each AST provided class +to a definition scope. The names of these operations are constructed by +prepending the string "add_" to the name of the IDL construct. So, to add +an interface to a definition scope, invoke the operation add_interface. +The operations are all defined virtual and are intended to be overridden in +classes derived from UTL_Scope. + +If the node was successfully added to the definition scope, the node is +returned as the result. Otherwise the node is not added to the definition +scope and NULL is returned. + +All add operation implementations in UTL_Scope return NULL. Thus, +only the operations which implement legal additions to a specific kind of +definition scope must be overridden in the implementation of that +definition scope. For example, in AST_Module the add_interface operation is +overridden to add the provided instance of AST_Interface to the scope and +to return the provided instance if the addition was successful. Operations +which were not overridden return NULL to indicate that the addition is +illegal in this context. For example, in AST_Operation the definition of +add_interface is not overridden since it is illegal to store an interface +inside an operation definition scope. + +The add operations are invoked in the actions in the Yacc grammar. The +following fragment is a representative example of code using the add +operations: + + AST_Constant *d = construct_a_new_constant(); + ... + if (current_scope->add_constant(d) == NULL) { // Failed + ... + } else { // Succeeded + ... + } + +BE INTERACTION DURING THE PARSING PROCESS +----------------------------------------- + +The add operations can be overridden in BE derived classes to let the BE +perform additional house-keeping work during the process of constructing +the AST. For example, a BE could keep separate lists of interfaces as they +are being added to a module. + +If you override an add operation in your BE, you must invoke the overridden +operation in the superclass of your derived class to allow the CFE to +perform its own house-keeping tasks. A good rule is to invoke the operation +on the superclass before you do your own processing; then, if the +superclass operation returns NULL, this indicates that the addition failed +and your own code should immediately return NULL. An example explains this: + +AST_Interface * +BE_Module::add_interface(AST_Interface *i) +{ + if (AST_Module::add_interface(i) == NULL) // Failed, bail out! + return NULL; + ... // Do your own work here + return i; // Return success indication +} + +We strongly advise you to only define add operations that override add +operations provided by the AST classes. Add operations which +do not override equivalent operations in the AST in effect +extend the semantics of the language accepted by the compiler. For +example, the CFE does not have an add_interface operation on +AST_Operation. If you were to define one in your BE_Operation class, +the resulting compiler would allow an interface to be +stored in an operation definition scope. The current CORBA specification +does not allow this. + +AST INHERITANCE SCHEME +---------------------- + +The AST classes all use public virtual inheritance to construct the +inheritance tree. This ensures that a class may appear several times in the +inheritance tree through different paths and the derived class's instances +will have only one copy of the inherited class's data. + +The use of public virtual inheritance has several important effects on how +a BE is constructed. We explain those effects below. + +First, you must define a default constructor for your BE class, since +your class may be used as a virtual base class of some other class. In this +case the compiler may want to call a default constructor for your class. It +is a good idea to have a default constructor anyway, even if you do not +plan to subclass your BE class, since for most C++ compilers this causes +the code to be smaller. Your default constructor should initialize all +constant data members. Additionally, it may initialize any non-constant +data member whose value must be set before the first time the instance is +used. + +Second, the constructor of your BE derived class must explicitly call all +constructors of virtual base classes which perform useful work. For +example, if a class in the AST from which your BE class inherits has an +initializer for a data member, you must call that constructor. This rule is +discussed in detail in the C++ ARM. An example may help here. + +Suppose you define a class BE_attribute which inherits from AST_Attribute. +Its constructor should be as follows: + + BE_Attribute::BE_Attribute(boolean ro, + AST_Type *ft, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Attribute(ro, ft, n, p), + AST_Field(ft, n, p), + AST_Decl(AST_Decl::NT_attr, n, p) + { + } + +The calls to the constructors of AST_Attribute, AST_Field and AST_Decl are +needed because these constructors do useful initializations on their +classes. + +Note that there is some redundancy in the data passed to these +constructors. We chose to preserve this redundancy since it should be +possible to create BEs which subclass only some of the classes supplied by +the AST. This means that the constructors on each class provided by the AST +should take arguments which are sufficient to construct the instance if +the AST class is the most derived one. + +The code supplied with this release contains a demonstration BE which +subclasses all the AST provided classes. The constructors for each class +provided by the BE are found in the file be/be_classes.cc. + +INITIALIZATION +-------------- + +The following steps take place at initialization: + +- The global data instance is created, stored in idl_global and filled with + default values (in driver/drv_init.cc). +- The command line arguments are parsed (in driver/drv_args.cc). +- For each IDL input file, a copy of the compiler process is forked (in + driver/drv_fork.cc). +- The IDL input is preprocessed (in driver/drv_preproc.cc). +- FE initialization stage 1 is done: the scopes stack is created and stored + in the global data variable idl_global->scopes() field (in fe/fe_init.cc). +- BE_init is called to create the generator instance and the returned + instance is stored in the global data variable idl_global->gen() field. +- FE initialization stage 2 is done: the global scope is created, pushed on + the scopes stack and populated with predefined types (in fe/fe_init.cc). + +GLOBAL STATE AND ENTRY POINTS +----------------------------- + +The CFE has one global variable named idl_global, which stores an instance +of a class IDL_GlobalData as explained below: + +The CFE defines a class IDL_GlobalData which defines the global +information used in a specific run of the compiler. IDL_GlobalData is +defined in include/idl_global.hh and implemented in the file +util/utl_global.cc. + +Initialization creates an instance of this class and stores it in the value +of the global variable idl_global. Thus, the individual pieces of +information stored in the instance are accessible everywhere. + +ERROR HANDLING +-------------- + +All error handling is defined by a class provided by the CFE, UTL_Error. +This class is defined in include/utl_error.hh and implemented in the file +util/utl_error.cc. The class provides several methods for reporting +specific errors as well as generic error reporting methods taking zero to +three arguments. + +The CFE instantiates the class and stores the instance as part of the +global state, accessible as idl_global->err(). Thus, to cause an error +report, you would write code similar to the following: + + if (error condition found) + idl_global->err()->specific_error_message(arg1, ..); + +or + + if (error condition found) + idl_global->err()->generic_error_message(flag, arg1, ..); + +The flag argument is one of the predefined error conditions found in the +enum at the head of the UTL_Error class definition. The arguments to the +specific error message routine are defined by the signature of that +routine. The arguments to a generic error message routine are always +instances of AST_Decl. + +The running count of errors is accessible as idl_global->err_count(). If +the value returned by this operation is non-zero after the IDL input has +been parsed, the BE is not invoked. + +HANDLING OF COMMAND LINE ARGUMENTS +---------------------------------- + +Defined command line arguments are specified in the document CLI, in this +directory. The CFE calls the required BE API entry point BE_prep_arg to +process arguments passed within a -Wb flag. + +REQUIRED ENTRY POINTS SUPPLIED BY A BE +-------------------------------------- + +The following API entry points must be supplied by a BE in order to +successfully link with the CFE: + +extern "C" AST_Generator *BE_init(); + + Creates an instance of the generator object and returns it. Note + that the global scope is not yet set up and the scopes stack is + empty when this routine is called. + +extern "C" void BE_produce(); + + Called by the compiler main program after the IDL input has been + successfully parsed and processed. The job of this routine is to + carry out the specific function of the BE. The AST is accessible as + the value of idl_global->root(). + +extern "C" void BE_prep_arg(char *, idl_bool); + + Called to process an argument passed in with a -Wb flag. The boolean + will always be FALSE. + +extern "C" void BE_abort(); + + Called when the CFE decides to abort the compilation. Can be used in + a BE to clean up after itself, e.g. remove temporary files or + directories it created while the parse was in progress. + +extern "C" void BE_version(); + + Called when a -V argument is processed. This should produce a + message for the user identifying the BE that is loaded and its + version information. + +PART II. WRITING A BACK END +-=========================- + +REQUIRED API THAT EACH BE MUST SUPPORT +-------------------------------------- + +Below are the API entry points that each BE must supply in order to use the +CFE framework. This is a repeat of the BE API section: + +extern "C" AST_Generator *BE_init(); + + Creates an instance of the generator object and returns it. Note + that the scopes stack is still not set up at the time this routine + is called. + +extern "C" void BE_produce(); + + Called by the compiler main program after the IDL input has been + successfully parsed and processed. The job of this routine is to + carry out the specific function of the BE. The AST is accessible as + the value of idl_global->root(). + +extern "C" void BE_prep_arg(char *, boolean); + + Called to process an argument passed in with a -Wb flag. The boolean + will always be FALSE. + +extern "C" void BE_abort(); + + Called when the CFE decides to abort the compilation. Can be used in + a BE to clean up after itself, e.g. remove temporary files or + directories it created while the parse was in progress. + +extern "C" void BE_version(); + + Called when a -V argument is processed. This should produce a + message for the user identifying the BE that is loaded and its + version information. + +WHAT FILES TO INCLUDE +--------------------- + +To use the CFE, each implementation file of your BE must include the +following two header files: + +#include <idl.hh> +#include <idl_extern.hh> + +Following this, you can include any header files needed by your BE. + +HOW TO SUBCLASS THE AST +----------------------- + +Your BE may subclass from any of the classes provided by the AST. Your +class should use public virtual inheritance to ensure that only one copy of +the class's data members is present in each instance. Read the section on +HOW TO WRITE CONSTRUCTORS to learn about additional considerations that you +must take into account when writing constructors for your BE classes. + +HOW TO SUBCLASS THE GENERATOR TO CREATE BE ENHANCED AST NODES +------------------------------------------------------------- + +Your BE subclasses from classes provided by the AST. To ensure that +instances of these classes are constructed when the AST is built, you must +also subclass AST_Generator and return an instance of your subclass from +the call to BE_init. + +The AST_Generator class provides operations to create instances of all +classes defined in the AST. For example, the operation to create an +AST_Attribute node is as follows: + + AST_Attribute * + AST_Generator::create_attribute(...) + { + return new AST_Attribute(...); + } + +In your BE_Generator subclass of AST_Generator, you will override methods +for creation of nodes of all AST classes which you have subclassed. Thus, +if your BE has a class BE_Attribute which is a subclass of AST_Attribute, +your BE_Generator class definition has to override the create_attribute +method to ensure that instances of BE_Attribute are created. + +The definition of the overriden operations should call the constructor of +the derived class and return the new node as an instance of the inherited +class. Thus, the implementation of create_attribute is as follows: + + AST_Attribute * + BE_Generator::create_attribute(...) + { + return new BE_Attribute(...); + } + +The Yacc grammar actions call create_xxx operations on the generator +instance stored in the global variable idl_global->gen() field. By storing +an instance of your derived generator class BE_Generator you ensure that +instances of the BE classes you defined will be created. + +HOW TO WRITE CONSTRUCTORS FOR BE CLASSES +---------------------------------------- + +As mentioned above, the AST uses public virtual inheritance to derive the +AST class hierarchy. This has two important effects on how you write a BE, +specifically how you write constructors for derived BE classes. + +First, you must define a default constructor for your BE class, since +your class may be used as a virtual base class of some other class. In that +case the compiler may want to call a default constructor for your class. It +is a good idea to have a default constructor anyway, even if you do not +plan to subclass your BE class, since for most C++ compilers this causes +the code to be smaller. Your default constructor should initialize all +constant data members. Additionally, it may initialize any non-constant +data member whose value must be set before the first time the instance is +used. + +Second, the constructor for your BE class must explicitly call all +constructors of virtual base classes which do some useful work. For +example, if a class in the AST from which your BE class inherits, directly +or indirectly, has an initializer for a data member, your BE class's +constructor must call the AST class's constructor. This is discussed +extensively in the C++ ARM. + +Below is a list showing how to write constructors for subclasses of each +class provided by the BE. For each AST class we show a definition of a +constructor for a derived class which calls all neccessary constructors on +AST classes: + +AST_Argument: + + BE_Argument::BE_Argument(AST_Argument::Direction d, + AST_Type *ft, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Argument(d, ft, n, p), + AST_Field(AST_Decl::NT_argument, ft, n, p), + AST_Decl(AST_Decl::NT_argument, n, p) + { + } + +AST_Array: + + BE_Array::BE_Array(UTL_ScopedName *n, + unsigned long nd, + UTL_ExprList *ds) + : AST_Array(n, nd, ds), + AST_Decl(AST_Decl::NT_array, n, NULL) + + { + } + +AST_Attribute: + + BE_Attribute::BE_Attribute(boolean ro, + AST_Type *ft, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Attribute(ro, ft, n, p), + AST_Field(AST_Decl::NT_attr, ft, n, p), + AST_Decl(AST_Decl::NT_attr, n, p) + { + } + +AST_ConcreteType: + + BE_ConcreteType::BE_ConcreteType(AST_Decl::NodeType nt, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Decl(nt, n, p) + { + } + +AST_Constant: + + BE_Constant::BE_Constant(AST_Expression::ExprType t, + AST_Expression *v, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Constant(t, v, n, p), + AST_Decl(AST_Decl::NT_const, n, p) + { + } + +AST_Decl: + + BE_Decl::BE_Decl(AST_Decl::NodeType nt, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Decl(nt, n, p) + { + } + +AST_Enum: + + BE_Enum::BE_Enum(UTL_ScopedName *n, + UTL_StrList *p) + : AST_Enum(n, p), + AST_Decl(AST_Decl::NT_enum, n, p), + UTL_Scope(AST_Decl::NT_enum) + { + } + +AST_EnumVal: + + BE_EnumVal::BE_EnumVal(unsigned long v, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_EnumVal(v, n, p), + AST_Constant(AST_Expression::EV_ulong, + AST_Decl::NT_enum_val, + new AST_Expression(v), + n, + p), + AST_Decl(AST_Decl::NT_enum_val, n, p) + { + } + +AST_Exception: + + BE_Exception::BE_Exception(UTL_ScopedName *n, + UTL_StrList *p) + : AST_Decl(AST_Decl::NT_except, n, p), + AST_Structure(AST_Decl::NT_except, n, p), + UTL_Scope(AST_Decl::NT_except) + { + } + +AST_Field: + + BE_Field::BE_Field(AST_Type *ft, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Field(ft, n, p), + AST_Decl(AST_Decl::NT_field, n, p) + { + } + +AST_Interface: + + BE_Interface::BE_Interface(UTL_ScopedName *n, + AST_Interface **ih, + long nih, + UTL_StrList *p) + : AST_Interface(n, ih, nih, p), + AST_Decl(AST_Decl::NT_interface, n, p), + UTL_Scope(AST_Decl::NT_interface) + { + } + +AST_InterfaceFwd: + + BE_InterfaceFwd::BE_InterfaceFwd(UTL_ScopedName *n, + UTL_StrList *p) + : AST_InterfaceFwd(n, p), + AST_Decl(AST_Decl::NT_interface_fwd, n, p) + { + } + +AST_Module: + + BE_Module::BE_Module(UTL_ScopedName *n, + UTL_StrList *p) + : AST_Decl(AST_Decl::NT_module, n, p), + UTL_Scope(AST_Decl::NT_module) + { + } + +AST_Operation: + + BE_Operation::BE_Operation(AST_Type *rt, + AST_Operation::Flags fl, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Operation(rt, fl, n, p), + AST_Decl(AST_Decl::NT_op, n, p), + UTL_Scope(AST_Decl::NT_op) + { + } + +AST_PredefinedType: + + BE_PredefinedType::BE_PredefinedType( + AST_PredefinedType::PredefinedType *pt, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_PredefinedType(pt, n, p), + AST_Decl(AST_Decl::NT_pre_defined, n, p) + { + } + +AST_Root: + + BE_Root::BE_Root(UTL_ScopedName *n, UTL_StrList *p) + : AST_Module(n, p), + AST_Decl(AST_Decl::NT_module, n, p), + UTL_Scope(AST_Decl::NT_module) + { + } + + +AST_Sequence: + + BE_Sequence::BE_Sequence(AST_Expression *ms, AST_Type *bt) + : AST_Sequence(ms, bt), + AST_Decl(AST_Decl::NT_sequence, + new UTL_ScopedName(new String("sequence"), NULL), + NULL) + { + } + +AST_String: + + BE_String::BE_String(AST_Expression *ms) + : AST_String(ms), + AST_Decl(AST_Decl::NT_string, + new UTL_ScopedName(new String("string"), NULL), + NULL) + { + } + +AST_Structure: + + BE_Structure::BE_Structure(UTL_ScopedName *n, + UTL_StrList *p) + : AST_Decl(AST_Decl::NT_struct, n, p), + UTL_Scope(AST_Decl::NT_struct) + { + } + +AST_Type: + + BE_Type::BE_Type(AST_Decl::NodeType nt, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Decl(nt, n, p) + { + } + +AST_Typedef: + + BE_Typedef::BE_Typedef(AST_Type *bt, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Typedef(bt, n, p), + AST_Decl(AST_Decl::NT_typedef, n, p) + { + } + +AST_Union: + + BE_Union::BE_Union(AST_ConcreteType *dt, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_Union(dt, n, p), + AST_Structure(AST_Decl::NT_union, n, p), + AST_Decl(AST_Decl::NT_union, n, p), + UTL_Scope(AST_Decl::NT_union) + { + } + +AST_UnionBranch: + + BE_UnionBranch::BE_UnionBranch(AST_UnionLabel *fl, + AST_Type *ft, + UTL_ScopedName *n, + UTL_StrList *p) + : AST_UnionBranch(fl, ft, n, p), + AST_Field(ft, n, p), + AST_Decl(AST_Decl::NT_union_branch, n, p) + { + } + +AST_UnionLabel: + + BE_UnionLabel::BE_UnionLabel(AST_UnionLabel::UnionLabel lk, + AST_Expression *lv) + : AST_UnionLabel(lk, lv) + { + } + +HOW TO USE THE ADD PROTOCOL +--------------------------- + +As explained the section SCOPE MANAGEMENT, the CFE manages scopes by +calling type-specific functions to add new nodes to the scope to be +augmented. These functions can be overridden in your BE classes to do work +specific to your BE class. For example, in a BE_module class, you might +override add_interface to do additional work. + +The protocol defined by the "add_" functions is that they return NULL to +indicate failure. They return the node that was added (and which was given +as an argument) if the operation succeeded. Your functions in your BE class +should follow the same protocol. + +The "add_" functions defined in the BE must call the overridden function in +the base class defind in the CFE in order for the CFE scope management +mechanism to work. Otherwise, the CFE does not get an opportunity to +augment its scopes with the new node to be added. It is good practice to +call the overridden "add_" function as the first action in your BE +function, because the success or failure of the CFE operation indicates +whether your function should complete its task or abort early. + +Here is an example. Suppose you have defined a class BE_module which +inherits from AST_Module. You may wish to override the add_interface +function as follows: + + class BE_Module : public virtual AST_Module + { + .... + /* + * ADD protocol + */ + virtual AST_Interface *add_interface(AST_Interface *); + ... + }; + +The implementation of this function would look something like the following: + + AST_Interface * + BE_Module::add_interface(AST_Interface *new_in) + { + /* + * Check that the CFE operation succeeds. If it returns + * NULL, stop any further work + */ + if (AST_Module::add_interface(new_in) == NULL) + return NULL; + /* + * OK, non-NULL, this means the BE can do its own work here + */ + ... + /* + * Finally, don't forget to return the argument to indicate + * success + */ + return new_in; + } + +HOW TO MAINTAIN BE SPECIFIC INFORMATION +--------------------------------------- + +The CFE provides a special class AST_Root, a subclass of AST_Module. An +instance of the AST_Root class is used as the distinguished root of the +abstract syntax tree built during a parse. + +Your BE can subclass BE_Root from AST_Root and override the create_root +operation in your BE_Generator class derived from AST_Generator. This will +cause the CFE to create an instance of your BE_Root class as the root of +the tree being constructed. + +You can use the instance of the BE_Root class as a convenient place to +store information specific to an individual tree. For example, you could +add operations on the BE_Root class to count how many nodes of each class +are created. + +HOW TO USE MEMBER DATA +---------------------- + +As explained above, the AST classes provide access and update functions for +manipulating data members. Your BE classes must use these functions when +they require access to data members defined in the AST classes, since the +data members themselves are private. + +It is good practice to follow the same scheme in your BE classes. Make all +data members private. Prepend the names of all such fields with "pd_". +Define access functions with names equal to the name of the field without the +prefix. Define update functions according to need by prepending the name of +the access function with the prefix "set_". + +Using these techniques will allow your BE to enjoy the same benefits that +are imparted onto the CFE. Your BE will be easier to move to a +multithreaded environment and its data members will be better protected and +hidden. + +HOW TO BUILD A COMPLETE COMPILER +-------------------------------- + +We now have all information needed to write a BE and to link it in with the +CFE, to produce a complete IDL compiler. + +The following assumes that your BE will be stored in the "be" directory +under the "release" directory. See the document ROADMAP for an explanation +of the directory structure of the source release. If you decide to use a +different directory to store your BE, you may have to modify the CPP_FLAGS in +"idl_make_vars" in the top-level directory to allow your BE to find the +include files it needs. You will also need to modify several targets in +the Makefile in the top-level directory to correctly compile your BE into a +library and to correctly link it in with the CFE to produce a complete +compiler. + +You can get started quickly on writing your BE by modifying the sources +found in the "demo_be" directory. The Makefile supports all the the targets +that are needed to build a complete system and the maintenance target +"clean" which assists in keeping the files and directories tidy. The files +provided in the "demo_be" directory also provide all the API entry points +that are mandated by this document. + +To build a complete compiler, invoke "make" or "make all" in the top-level +directory. This will compile your BE and all the CFE sources, if this is +the first invocation. On subsequent invocations this will recompile only +the modified files. You will rarely if at all modify the CFE sources, so +the overhead of compiling the CFE is incurred only the first time. To build +just your BE, you can invoke "make all" or "make" in the "demo_be" +directory. You can also, from the top-level directory, invoke "make +demo_be/libbe.a". + +HOW TO OBTAIN ASSISTANCE +------------------------ + +First, read all the documents provided. If you have unanswered questions, +mail them to + + idl-cfe@sun.com + +Sun does not promise to support the IDL CFE source release in any manner. +However, we will attempt to answer questions and correct problems as time +allows. + +NOTE: + +SunOS, SunSoft, Sun, Solaris, Sun Microsystems or the Sun logo are +trademarks or registered trademarks of Sun Microsystems, Inc. + +COPYRIGHT NOTICE +---------------- + +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 |