# Copyright 1993-1999, by the Cecil Project # Department of Computer Science and Engineering, University of Washington # See the $VORTEX_HOME/notes/LICENSE file for license information. This directory contains notes for the UW Cecil/Vortex 3.0 distribution. See the INSTALL file in this directory for installation directions. See the QUICK-START-CECIL file for information on how to use the simple Cecil read-eval-print interpreter. See the QUICK-START-VORTEX file for information on how to compile a simple Cecil program using Vortex. See thingsWeAreNotProudOf.txt and bugs.txt for a list of limitations and bugs in our implementation. See our web page for more information, or email us if you have feedback or questions not answered here: http://www.cs.washington.edu/research/projects/cecil cecil@cs.washington.edu CONTENTS A guide to the vortex tree Available documentation Architecture/OS/front-end-specific notes A list of third party software used by Vortex ****************************************************************************** ** A guide to the vortex tree ****************************************************************************** Notation -------- $VORTEX_BASELINE, $VORTEX_HOME The top-level directory. $VORTEX_BASELINE refers to the location where the Vortex distribution is unpacked. $VORTEX_HOME refers to the current user's copy of the Vortex distribution, or just $VORTEX_BASELINE if there is only one copy of the Vortex distribution. (These variables are set by $VORTEX_HOME/bin/shell/vortex.cshrc) $VORTEX_ARCH The name used to denote the architecture/OS combination on the machine where Vortex is being installed or run (it is part of the name of the tar file that you download, and is also printed by $VORTEX_HOME/bin/shell/vortex-arch; this variable is set by $VORTEX_HOME/bin/shell/vortex.cshrc) $VORTEX_MAKE The name of the GNU make program on your system (set in $VORTEX_HOME/bin/shell/vortex.cshrc) The name of a certain front-end (Cecil, Java, M3, etc.), or Vortex (denotes the common components of the distribution) Main parts of the vortex tree ----------------------------- $VORTEX_HOME top-level directory $VORTEX_HOME/notes various notes, including this file, INSTALL, LICENSE, etc., primarily for users who are interested in installing or developing Vortex (see "Available documentation" below) $VORTEX_HOME/doc comprehensive manuals on using Vortex and Cecil (see "Available documentation" below) $VORTEX_HOME/bin contains a number of tools/scripts invoked by Vortex or used for program development or experimentation $VORTEX_HOME/runtime source and object files for the vortex runtime system and various supporting libraries $VORTEX_HOME/Cecil Cecil front-end: sources/scripts/support for Cecil programs sources for Vortex (see below for details) $VORTEX_HOME/C++ $VORTEX_HOME/Java $VORTEX_HOME/Smalltalk $VORTEX_HOME/M3 C++, Java, Smalltalk, and Modula-3 front-ends; include sources of sample programs and/or front-end executabes, support scripts and front-end binaries See the $VORTEX_HOME/{C++,Java,Smalltalk/{parcplace,ibm},M3}/README files for more info on using the non-Cecil front-ends for Vortex (these README files come with their respective front-ends). $VORTEX_HOME/SETUP-.$VORTEX_ARCH.done These files are generated by the SETUP script Structure of the Cecil front-end -------------------------------- $VORTEX_HOME/Cecil/bin tools and scripts for manipulating Cecil programs $VORTEX_HOME/Cecil/lib precompiled (unoptimized) versions of the Cecil standard libraries $VORTEX_HOME/Cecil/src Cecil source code $VORTEX_HOME/Cecil/src/{compiler,stdlib} Cecil source code for the Vortex compiler, the Cecil standard library, and the Cecil interpreter ****************************************************************************** ** Available documentation ****************************************************************************** Here are the places to look for information: $VORTEX_HOME/{notes,doc} discussed below $VORTEX_HOME/{C++,Java,Smalltalk/{parcplace,ibm},M3}/README information on using the non-Cecil front-ends for Vortex (these come with their respective front-ends) http://www.cs.washington.edu/research/projects/cecil our web page with documentation, papers, project members, sources of our support, and more Here are files in $VORTEX_HOME/notes, included with the distribution: README this file LICENSE licensing information INSTALL installation instructions FAQ some frequently asked questions and tips CECIL-FEATURES a summary of features of the Cecil language VORTEX-FEATURES a summary of features of the Vortex compiler QUICK-START-CECIL how to use Cecil read-eval-print interpreter QUICK-START-VORTEX how to compile sample Cecil program with Vortex compiler-intro.txt an overview of the Vortex compiler source code gc.txt some GC documentation thingsWeAreNotProudOf.txt limitations of our implementation bugs.txt outright bugs we are aware of SETUP..sample-output sample output of running the SETUP script Here are manuals in $VORTEX_HOME/doc: (common for all front-ends:) vortex.ps Vortex compiler user's guide vortex-benchmarking.ps Hints on benchmarking vortex-compiled apps. (come with the Cecil front-end:) cecil-spec.ps Cecil language specification stdlib.ps Cecil stdlib reference manual (also available from the release web page:) Textual Vortex RTL specification Pragmas currently understood by Vortex ****************************************************************************** ** Architecture/OS/front-end-specific notes ****************************************************************************** The Sparc/SunOS and Sparc/Solaris versions of the release are the only ones that include several lowlevel machine/OS-dependent performance optimizations, including dynamically generated message dispatchers (PICs) and unaligned signal handlers for faster class tests in the face of tagged integers (as used in Cecil and Smalltalk, but not Java or C++). Let us know if you desire similar low-level support on another architecture. 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. Or compile the libraries yourself, using the vortex-CC-native program to compile them instead of the g++ compiler. (Since each C++ front-end defines its own name-mangling scheme, object layout, and so on, we have to compile all code, including libraries, with our EDG-based C++ front-end for the compiled code to interoperate. However, some g++ libraries use g++-specific extensions, so they *can't* be compiled with other C++ compilers (like EDG) directly. Something of a Catch-22. And there are other small random variations in C++ dialect compiled by different C++ compilers, so compiling C++ programs or libraries with a compiler other than the one they were developed under is fraught with difficulty.) 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. The ParcPlace Smalltalk front-end works, but only a subset of primitives and classes are supported (excluding all graphics/UI primitives and classes). The IBM Smalltalk front-end is only partially implemented. ** 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 PA9000/HPUX release ** -- The system has been ported, but it has not been extensively tested. We do not have local access to an HP machine, so we cannot test the port extensively ourselves. ** Notes for the x86/Linux release ** -- There seem to be different versions of Linux or of GCC/G++ on Linux. Our code works for our version of Linux (2.0.33) and GCC/G++ (2.7.2.1), but doesn't appear to work cleanly for other versions. Known potential problems (marked by the text LINUX VERSION PROBLEM) are in the following files: $VORTEX_HOME/runtime/gc/conservative-gc/src/os_dep.c $VORTEX_HOME/runtime/pic/src/types.h $VORTEX_HOME/runtime/pic/src/cecil.c $VORTEX_HOME/runtime/minimal/src/vortex-defs.c $VORTEX_HOME/C++/src/tests/getrusage.h $VORTEX_HOME/Java/stdlib/native/java.lang.System.class.native.rtl $VORTEX_HOME/Java/stdlib/native/file-ops.rtl [Note that for the last two files above, you need to edit the source .rtl files, not the generated .rtl.c files.] ** Notes for the x86/WindowsNT release ** -- The system has been ported using the CYGWIN suite of UNIX-like tools and libraries, available from http://sourceware.cygnus.com/cygwin. Since NT+CYGWIN isn't a full Unix, some support utilities may not work as well as they do under a real Unix. ** Porting to a new architecture/OS combination ** -- Does not address 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 $VORTEX_HOME/bin/shell/vortex-arch to define a new architecture name (referred to henceforth as $VORTEX_ARCH). In the $VORTEX_HOME/runtime/makefiles directory, add VortexConfig.$VORTEX_ARCH and ArchConfig.$VORTEX_ARCH files based on the combinations already defined. In the $VORTEX_HOME/runtime/{pic,minimal}/src directories, add RuntimeMakefile.$VORTEX_ARCH files based on the ones already defined and create empty Runtime{Dependency,HeaderDep}Info.$VORTEX_ARCH files. 3) Port & build the make support programs "lock-run" and "zap". Ideally, this should be as simple as going to the directory $VORTEX_HOME/bin/src and typing "$VORTEX_MAKE". If successful, the directory $VORTEX_HOME/bin/$VORTEX_ARCH 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 $VORTEX_HOME/runtime/gc/conservative/src followed by invoking "$VORTEX_MAKE". The directory $VORTEX_HOME/runtime/gc/conservative/$VORTEX_ARCH 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. "$VORTEX_MAKE test" is a good way to do some simple tests of the library. 5) You are finally ready to build the vortex executable: cd to $VORTEX_HOME/vortex-C-files. Type "$VORTEX_MAKE depend" to create the architecture's runtime system's dependency files. Then either type "$VORTEX_MAKE" or "pm" to start compiling the C files. We recomend initially using "$VORTEX_MAKE" 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 $VORTEX_HOME/runtime/pic/src) to work around various OS-specific quirks. A few of the C++ primitives in {{double,single}-float,file,randstream,specialized,system,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 $VORTEX_HOME/bin/$VORTEX_ARCH/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 $VORTEX_HOME/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_HOME/runtime/gc/conservative-gc/src. ** The UMass accurate garbage collection toolkit. For more information see $VORTEX_HOME/runtime/gc/accurate-gc. ** The NJ machine code toolkit. For more information see $VORTEX_HOME/runtime/njtoolkit/src. ** Our Java front-end is derived from the javap disassembler provided in the Sun JDK1.0. ** Our C++ front-end is based on the EDG C++ front-end. We cannot distribute source to this program, but a binary is included in the distribution. ** Our Modula-3 front-end is derived from the DEC SRC Modula-3 implementation. ** Vortex can utilize the dot program from AT&T 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_HOME/bin/shell/display-dot to refer to your local dot installation.