------------------------------------------------------------------------ Assertion Definition Language (ADL) TRANSLATION SYSTEM 2.1 RELEASE NOTES ------------------------------------------------------------------------ Copyright (c) 1996-1998 Information-technology Promotion Agency, Japan Copyright (c) 1996-1998 Mitsubishi Research Institute, Inc. Copyright (c) 1996-1998 The Open Group All rights reserved. Permissions to use, copy, modify and distribute this software are governed by the terms and conditions set forth in the file COPYRIGHT, located in the top directory of this software. $Source: /vobstore/cvsstore/adl/adl2/RELEASE_NOTES,v $ $Revision: 1.9 $ $Date: 1998/11/25 07:59:27 $ This document briefly describes the details of the ADL Translation System ("adlt"), version 2.1. This release of the ADL 2 Translation System is a fully functional deliverable, intended for evaluation and experimental use. Its limitations are described in section 5 of this file. The information below includes the instructions for installing and running the ADL 2 Translation System. The MANIFEST file located in this directory gives a detailed listing of the contents of the ADL 2 Translation System release directory. These release notes are divided into the following sections: 1. ADLT 2 Component Current Versions 2. Installation 3. Using Release 2.1 4. Examples Directory 5. Current Limitations and Bugs 6. Acknowledgments 1. ADLT Component Current Versions ================================== Component Version -------- ------- ADLT 2.0 Design Specification Version 1.1 ADL 2.0 for C++ Language Reference Manual Version 1.2 ADL 2.0 for Java Language Reference Manual Version 1.2 ADL 2.0 for IDL Language Reference Manual Version 1.2 ADL 2.0 for C Language Reference Manual Version 1.1 ADL 2.0 for C++ Compiler Version 1.2 ADL 2.0 for Java Compiler Version 1.2 ADL 2.0 for C Compiler Version 1.1 ADL 2.0 Runtime for C++ Version 1.2 ADL 2.0 Runtime for Java Version 1.2 ADL 2.0 Runtime for C Version 1.1 2. Installation =============== Required Software ----------------- 1) Java Compiler and Developers Kit. The ADL 2 compilers require the Java Developer's Kit (JDK) version 1.1 to be installed on your system. The Java Developer's Kit may be downloaded from http://java.sun.com/. 2) Objectspace's JGL The ADL 2 compilers require that the Objectspace's JGL library is installed on your system. Version 3.1.0 of this library is provided in the ADL 2 distribution. See lib/jgl/COPYRIGHT.TXT and lib/jgl/LICENSE.TXT for copyright and licensing issues regarding this library. 3) C++ compiler To build the C++ runtime environment you need to have access to a C++ compiler. We have successfully built the C++ runtime environment with the Gnu C++ compiler, version 2.7.2 and with Sun's C++ compiler, version 4.2. Egcs 1.0.1 has also been used successfully to build the runtime library though some strange problems occur later during test execution when catching an unknown exception. In addition, to be able to use the ADL 2 C++ compiler, you need to have an ANSI C preprocessor installed on your system. To compile the C++ examples you need to have a C++ compiler installed on your system. Be sure to use the same compiler as the one used to build the runtime environment. 4) C compiler To build the C runtime environment you need to have access to a C compiler. Any ANSI compliant C compiler will do. We have successfully built the C runtime environment with the Gnu C compiler, version 2.7.2. In addition, to be able to use the ADL 2 C compiler, you need to have an ANSI C preprocessor installed on your system. To compile the C examples you need to have a C compiler installed on your system. Be sure to use the same compiler as the one used to build the runtime environment. 5) TET and JETPack Tests built using the ADL 2 Translation System are driven by the Test Execution Toolkit (TET) test harness. TET is therefore required to build the ADL 2 runtime environment and to operate any ADL2 generated test. Java tests further requires the installation of the Java Enhanced TET package (JETPack). Both these packages can be obtained from http://tetworks.opengroup.org/. 6) Prolog interpreter To be able to generate the documentation associated to your ADL specification and test definitions, you need to install a Prolog interpreter and make it known to the compiler. If you don't have one available, the easiest is certainly to get the one provided for the ADL 2 Translation System in adl2.1-prolog.tar.gz and unpack this archive where you unpacked the ADL 2 Translation System archive before you start building or installing it. If you already have a Prolog interpreter available, be sure its prompt is what ADL 2 expects, that is '?- '. Then, make it known to the ADL 2 Translation System by defining the 'adl.prolog' property in the $ADL2HOME/Adlt.rc file (see 8 in section 'Installing the ADL 2 Translation System'). 7) Gzip and tar The ADL Translation System, version 2.1 is packaged as a compressed tar archive. In order to unpack the distribution, you will need 'gunzip' and 'tar' utilities; if these are unavailable to you, please contact us to arrange for delivery in a different format. Installing the ADL 2 Translation System --------------------------------------- After acquiring the tar file and creating a directory to hold the system, you can install adlt by changing to the directory under which you want to unpack the ADL system and executing the following shell commands: 1) Unpack the archive, creating a directory named "adl2". gunzip adl2.1.tar.gz tar xvf adl2.1.tar 3) Change to the installation directory. cd adl2 4) Before using adlt you must set the environment variable ADL2HOME. ADL2HOME should be set to the directory in which you will be installing ADLT. setenv ADL2HOME `pwd` 5) Ensure that you can execute the Java virtual machine (java). You do not need to set your CLASSPATH; as long as ADL2HOME is set correctly, the provided scripts will add the necessary directories to CLASSPATH before invoking the parsers. 6) Copy in the file $ADL2HOME/Makefile.vars the configuration file for your platform in the config directory. Edit this file to set the different variables to their appropriate value (Java tools, TET_ROOT, ...). 7) Type make install; this will build the adlt command and C++ runtime environment. All other files needed by the ADL 2 compilers are precompiled. 8) Be sure to define the appropriate default values for the options in $ADL2HOME/Adlt.rc. This is the system-wide configuration file for the ADL Translation System. Manifest -------- A file named MANIFEST is supplied as part of the release; it lists all the files in the release, so you can verify that you have an intact distribution. Installing from a source distribution ------------------------------------- If you got the ADL 2 Translation System from a full source distribution, you will need to get the Java Compiler Compiler tool set to build the ADL 2 compilers and install them (see section 6. Acknowledgments in this file). Ignore the remainder of this section if you got the ADL 2 Translation System from a standard distribution. The installation procedure requires an additional step 6bis before step 7. 6bis) Type make compiler; this will generate the parsers for all the target languages, compile all the Java classes that make up the ADL 2 compilers and the Java runtime environment, and build a jar file for both. 3. Using Release 2.1 ==================== Running the ADL 2 compilers --------------------------- The ADL 2 compilers can all be invoked by the single adlt command. Refer to the ADL 2.0 User's Guide for a complete description of the adlt command. Running the ADL 2 examples -------------------------- The ADL 2 release distribution contains a set of examples for Java, C++, C and IDL. These examples can be compiled with adlt and run with TET. Refer to the README file in the example directories for more detailed information on a specific example. 4. Examples Directory ===================== Contents -------- The examples directory has examples of ADLT input for each of the target languages. Examples can generally be processed by doing 'make' in the example directory, except IDL examples which require the ORB to be setup as well and for which a README file giving comments on the example and instructions for processing it is provided. The examples provided are: C++ examples ------------ bank_example -- This is C++ version of the bank example. The bank example is a full demonstration of ADL version 2 specification and testing capabilities. The SGML documentation for this example can be generated by doing 'make doc'. StockBroker -- This example is taken from the "ADL for C++ Language Reference Manual"; it illustrates the use of all semantic annotation features of ADL for C++. This example only comes with a header file describing the API of a StockBroker object and its specification in ADL. IDL examples ------------ bank_example -- This is the IDL version of the bank example. This example is a full exercise of ADL 2's semantic and test annotation capabilities. stock_example -- This example is taken from the "ADL for IDL Language Reference Manual"; it illustrates the use of all semantic annotation features of ADL for IDL, and of the ORBWrapper helper class. Java examples ------------- bank_example -- This is Java version of the bank example. The bank example is a full exercise of ADL 2 specification and testing capabilities. The SGML documentation for this example can be generated by doing 'make doc'. stock_example -- This is Java version of the StockBroker example as it appears in the ADL for Java Language Reference Manual. unit -- This example illustrates the use of ADL in specification and testing of base and inherited Java classes. The class Unit and its descendants implement a simple time calculator. C examples ---------- simple_bank -- This is a very limited C version of the bank example. bank_example -- This is C version of the bank example. The bank example exercises most of ADL 2 specification and testing capabilities. StockBroker -- This is the C version of the Stock Broker example, only to illustrate the definition of the ADL specifications for this API. 5. Current Limitations and Bugs =============================== Hopefully, there are no serious known bugs in this release. In case you find one, please report it to adl-support@gr.opengroup.org. Following is a description of the current limitations of the ADL 2 Translation System. All language bindings --------------------- 1) The documentation generation proceeds even when the syntax of the NLD annotations is incorrect. ADL for Java, ADL for IDL ------------------------- 1) Java anonymous array initializer (JDK1.1.1 and above) are not recognized by the ADL compiler. For example, the Java construct : String[] someStrings = { "foo", "bar" }; cannot be used in ADL specifications, instead use : String[] someStrings = new String[2]; someStrings[0] = "foo"; someStrings[1] = "bar"; 2) Java '.class' notation (JDK1.1.1 and above) to get the static class of a class given its name (e.g. String.class) is not yet implemented. ADL for C++ ----------- 1) Generic classes, i.e., templates, are not supported by the ADL for C++ compiler. 2) Use of ellipsis "..." in parameter declaration is not fully supported. For instance, a function void foo(int a, ...); is known to the compiler as void foo(int) The function call "foo(1,2)" is reported as not valid. 3) Likewise, default values for parameters of a method are ignored. For instance a method declared as void bar(int a, int b=0); should always be called with two arguments. 4) Specification and test of operators is supported only using explicit operator function call like: myObj->operator+(anotherObj); However, this is not a real limitation. 5) No type ckeck is done for C++ initializers. For example, in the construct: struct conf { char * month; int year; char * location ; } cpp[] = { "November",1987,"San Francisco", "October",1988,"LA" }; the initialization value is not type checked and no type compatibility between the declarator and the initializer is verified. For a TDD variable declaration, initialization expression can only be an assignment expression and may not be an initializer list. 6) Declaration of arrays: C++ requires that the array size must be a constant. This is not checked by the ADL compiler and left to the C++ compiler afterwards. 7) Pre-processor specific symbols are not supported. Some pre-processors (e.g., egcs 1.x or gcc 2.8.x), may include non standard builtin symbols. These symbols do not match our grammar (based on the standard C++ grammar) and cause the compiler to fail. 8) Functions or methods returning an array or array variables may not appear as a member of a binary logical expression ('&&' or '||') in an assertion. The ADL compiler is effectively unable to initialize a temporary variable representing this member in the generated code. ADL for C --------- 1) No check is done to verify that the initializater expression of a TDD field is a valid constant expression as defined by the ANSI C standard. This is too hard a job for the ADL compiler. Instead, a warning may be emitted when another TDD field is used in the initializer expression. The final verification is left to the C compiler afterwards. 2) No type ckeck is done for C initializers. For example, in the construct: struct conf { char * month; int year; char * location ; } cpp[] = { "November",1987,"San Francisco", "October",1988,"LA" }; the initialization value is not type checked and no type compatibility between the declarator and the initializer is verified. For a TDD variable declaration, initialization expression can only be an assignment expression and may not be an initializer list. 3) Declaration of arrays: C requires that the array size must be a constant. This is not checked by the ADL compiler and left to the C compiler afterwards. 4) Pre-processor specific symbols are not supported. Some pre-processors (e.g., egcs 1.x or gcc 2.8.x), may include non standard builtin symbols. These symbols do not match our grammar (based on the standard C grammar) and cause the compiler to fail. 5) Functions or methods returning an array or struct or union, or array|struct|union variables may not appear as a member of a binary logical expression ('&&' or '||') in an assertion. The ADL compiler is effectively unable to initialize a temporary variable representing this member in the generated code. 6. Acknowledgments ================== The ADL 2 parsers are generated using the Java Compiler Compiler tool set: javacc and jjtree, version 0.8 pre 1 or above. You do not need to have these tools installed to install the ADL 2 Translation System since the generated parsers are provided in this release. The Java Compiler Compiler tool set can be freely downloaded from http://www.metamata.com/JavaCC/.