# Copyright 1993-1997, by the Cecil Project # Department of Computer Science and Engineering, University of Washington # See the LICENSE file for license information. This directory contains the UW Cecil/Vortex 2.0 distribution. See the INSTALL file in this directory for installation directions. Contents: Overview A guide to the vortex tree Architecture/OS specific notes A list of third party software utilized by Vortex Current list of known bugs and limitations ****************************************************************************** ** Overview ****************************************************************************** Cecil is a purely object-oriented language intended to support rapid construction of high-quality, extensible software. Cecil incorporates multi-methods, a simple prototype-based object model, a mechanism to support a structured form of computed inheritance, module-based encapsulation, and a flexible static type system which allows statically- and dynamically-typed code to mix freely. Vortex is an optimizing compiler infrastructure for object-oriented and other high-level languages. It targets both pure object-oriented languages like Cecil and hybrid object-oriented languages like C++, Modula-3, and Java. Vortex currently incorporates high-level optimizations such as static class analysis, class hierachy analysis, profile-guided receiver class prediction, profile-guided selective procedure specialization, intraprocedural message splitting, automatic inlining, and static closure analyses. It also includes a collection of standard intraprocedural analyses such as common subexpression elimination and dead assignment elimination. The Vortex compiler is written entirely in Cecil. Please see the INSTALL file for instructions on how to setup the distribution. Once setup is complete, you can use the script /vortex/bin/shell/run-vortex to run the vortex compiler. See the README files in the C++, Java, and M3 subdirectories for instructions on using the C++, Java, and Modula-3 front ends. ****************************************************************************** ** A guide to the vortex tree ****************************************************************************** /vortex top-level directory, LICENSE file, INSTALL file, this file /vortex/bin /vortex/Cecil/bin contain a number of tools/scripts used to compile Cecil programs, gather profile information, etc. /vortex/doc cecil-spec.ps Cecil language specification rtl-grammar.ps Textual RTL specification stdlib.ps Cecil stdlib reference manual vortex.ps Vortex compiler user's guide vortex-benchmarking.ps Hints on benchmarking vortex-compiled apps. /vortex/Cecil/lib precompiled (unoptimized) versions of the Cecil standard libraries /vortex/Cecil/src Cecil source code /vortex/C++ C++ versions of some small benchmarks measured in various papers scripts/support for C++ front end /vortex/Java scripts/support/sources for Java front end /vortex/M3 scripts/support for M3 front end /vortex/runtime source & object files for the vortex runtime system and various supporting libraries. ****************************************************************************** ** Architecture/OS specific notes ****************************************************************************** NOTE: The Sparc/SunOS and Sparc/Solaris versions of the release are the only configurations of the system that we use regularly and thus are the most thoroughly tested. They are also the only configurations that include several lowlevel machine/OS-dependent performance optimizations. Higher performance ports for a subset of the other configurations are planned for the not-so-immediate future. NOTE: Currently Vortex can only link compiled C++ programs on Sparc/SunOS, since we have not yet built all the necessary C++/libg++ libraries on other architectures. If you wish to link Vortex-compiled C++ programs on other architectures, get in touch with us (cecil@cs.washington.edu) to try to arrange for appropriate libraries to be constructed. NOTE: the Modula-3 front end only runs on Sparc/SunOS. It is not included in this release; if you are interested in compiling Modula-3 programs with Vortex, get in touch with us (cecil@cs.washington.edu) for more information. ** Notes for the Sparc/SunOS (version 4.x) release ** -- We assume that the target machine is a supersparc (implements the V8 architecture). If you are running on an older V7 (IPX, SPARC1, SPARC2) machine, you will need to get the C-only distribution, modify the line in the ArchConfig.sun4 makefile that specifies that the target is a supersparc, and build the system yourself. ** Notes for the Sparc/Solaris (a.k.a. SunOS 5.x) release ** ** Notes for the Alpha/OSF1 release ** ** Notes for the PowerPC/AIX release ** ** Notes for the x86/Linux release ** ** Porting to a new architecture/OS combination ** -- Does not include non-Cecil front-ends 1) You should have gotten the C-only distribution, which contains the Vortex generated C++ code for the vortex.cecil program. 2) Define the arch/OS combination you want: -- extend /bin/shell/arch to define an -- in the /runtime/makefiles directory, add VortexConfig. and ArchConfig. files based on the combinations already defined. 3) Port & build the make support programs 'lock-run' and 'zap'. Ideally, this should be as simple as going to the directory /bin/src and typing 'gmake'. If successfully, the directory /bin/ should contain the 'lock-run' and 'zap' executables. 4) Port & build the Boehm-Weiser conservative garbage collector. Again, in the best case this is a cd to the directory /runtime/gc/conservative/src followed by a 'gmake'. The directory /runtime/gc/conservative/ should contain the files libconservativegc.a and gctest, a simple sanity tester for the gc system included with its distribution. You may want/need to read the release notes included with the gc library. 5) You are finally ready to build the vortex executable, cd to /vortex-C-files and either type 'gmake' or 'pm' to start compiling the C files. We recomend initially using 'gmake' to compile the files one at a time until all the kinks have been resolved and then switching to 'pm'. You may need to edit runtime system files (in ) to work around various OS-specific quirks. A few of the C++ primitives in double-float.cecil, randstream.cecil, single-float.cecil, system.cecil, and time.cecil also contain OS-specific #defines (VORTEX_SUN4, VORTEX_POWERPC, etc.) that may need to be extended. 6) cp/mv the vortex executable to /bin//vortex You should now be ready to go. The first time you build a Cecil executable, .a files for the Cecil standard libraries will be automatically compiled from the precompiled C++ files included in the release (in /Cecil/lib/...>). ****************************************************************************** ** Included third party software -- thanks!!! ****************************************************************************** The Cecil/Vortex distribution utilizes several third party software packages and tools; whenever possible we have included the full source of these packages in our distribution. We use and have included the following tools and libraries: ** The Boehm-Weiser conservative garbage collector from Xerox. For more information see /vortex/runtime/gc/conservative-gc-*/src. ** The UMass accurate garbage collection toolkit. For more information see /vortex/runtime/gc/accurate-gc. ** The NJ machine toolkit. For more information see /vortex/runtime/njtoolkit/src. ** Our Java front end is derived from the disassembler provided in JDK1.0. We have not included source code in the distribution; we might be able to distribute source code in some circumstances. ** We have developed a M3 front end derived from the SRC Modula-3 implementation. Due to its fairly large size and low anticipated demand, we have not included the Modula-3 front end in this distribution. Let us know if you are interested in getting the M3 front end. ** We have developed a C++ front end based on the EDG C++ front end. We cannot distribute source to this program, however a binary is included in the distribution. Vortex can utilize the dot program from AT&T Bell labs to visually display control flow graphs and class hierarchies. You can download dot for free from http://www.research.att.com/sw/tools/graphviz/. To enable dot, simply edit /vortex/bin/shell/display-dot to refer to your local dot installation. ****************************************************************************** ** Bugs and Limitations ****************************************************************************** For a full list of some of the less critical limitations and bugs, see /notes/thingsWeAreNotProudOf.txt and bugs.txt. IMPLEMENTATION LIMITATIONS ** The implementation distinguishes between fully-functional (but slower) non-LIFO closures (identified with a leading && prefix) and regular LIFO closures (identified with a leading & prefix, or if the prefix is omitted altogether). If a LIFO closure turns out to be non-LIFO and accesses a variable from a lexically-enclosing (but not global) scope that has returned already, bad things can happen. Note that some bad things include fatal errors during compilation; we should fix things so that at least a warning message is displayed whenever we detect statically that a closure is non-LIFO. ** Stack overflows are not checked: the program just dumps core after printing a message. ** Overflow checking is not performed on integer arithmetic by default; the +_ov et al. operations must be used to perform overflow checking (but these operations are substantially slower than the + et al. operations). ** Nesting declarations other than variable declarations in a method or closure isn't supported. Nested methods in particular are missed. ** Parameterized objects aren't fully supported. In particular, a method cannot be attached to a particular instance of a parameterized type, only to all instances of the parameterized type. Also, a field specialized on a parameterized object should be replicated for each instantiation of the parameterized object; today there's just one copy. An explicitly parameterized field also only leads to one shared memory location. These both can be a type loop-hole if the type of the field's contents depends on its parameter. In other words, to the run-time implementation, all instances of a parameterized object/method/field are the same. ** Static type checking isn't fully implemented. Client-side typechecking is implemented, for all but the most complicated parameterization schemes, but implementation-side checking is completely missing. Dependencies that would trigger selective retypechecking are not implemented, either. (Partial) typechecking is performed only when explicitly invoked. ** Encapsulation declarations and module declarations are ignored. ** User-defined objects can't inherit from the pre-defined objects int, float, char, {i,m}_{float_,word_,}vector, {i,m}_vstring, unix_file, and env. On a related note, fields cannot be added to these objects (or to any ancestors of these objects). This should be fixed by making the internal fields associated with these objects visible to the field layout code in Vortex, e.g. by introducing a prim_field declaration for these "hidden" fields. ** The runtime system doesn't allow more than 20 arguments to a method; to increase this, add lines to the SLOW_PIC_TEMPLATES macro and add additional DUMMY_PARAMS macros in the pic.c file in the runtime system. ** The current implementation does not check to make sure that a routine that returns void is not called in a value-expecting context. Void can be passed as an argument to a method whose corresponding formal is unspecialized. So void acts like a special object that is a child of any, rather than being an ancestor of any as specified by the language. OUTRIGHT BUGS ** Object expressions of the form "object isa foo, bar" are broken if foo and bar have different fields attached to them. The problem is that we need to generate an offset method, specialized on anon_foo:anon_bar and we can't do that currently. ** Incremental update of some kinds of changes are not implemented completely correctly now. If you remove an object that has methods in an unchanged file, it might not detect the bug. If you replace an object with a global var, illegally, the object binding will not be restored to the global scope. ** There's a bug in how we update line numbers for Cecil debugging. We only update the current scope's line number, not any dynamically-enclosing scopes (for inlined scopes). ** The top-level declarations are not executed in the right order in the presence of include declarations. That is, if file A include's files B, C, and D, then the top-level declarations in B, C, D will be executed first, before executing the top-level declarations in A -- even if the include declarations in A are intermixed with other top-level declarations. ** Adding a (** debug **) pragma to a method does not result in the invalidation/re-compilation of any callers in which the method has been statically bound but not inlined. ** compiler-browser.cecil doesn't handle properly descendants of predicate objects, and fields whose two accessors have different privacy specs. However, the latter could be just a (non-fatal) bug in what privacy is stored at field_method_decl.