# Copyright 1993-2006, by the Cecil Project # Department of Computer Science and Engineering, University of Washington # See the $VORTEX_HOME/notes/LICENSE file for license information. To install the Vortex distribution, follow the steps below. To run Vortex etc. on Windows, you need to first install the Cygwin suite of Unix-like tools for Windows, available from http://www.cygwin.com; you need at least gcc/g++, make, tcsh, and perl, in addition to the basic cygwin tools. To run Vortex on multiple architectures, read the note at the end. For information on porting to a new architecture/OS combination, see the notes at the end of this file. ------------------------------ --- INSTALLATION AND SETUP --- ------------------------------ 1) Create a directory for the installation - $VORTEX_BASELINE You will need 100-200 MB of disk space, depending on your architecture and selection of front-ends. In our notes, $VORTEX_BASELINE stands for the chosen directory. 2) Download the tar files from the release web page or the FTP directory: http://www.cs.washington.edu/research/projects/cecil/www/Release ftp://ftp.cs.washingtion.edu/pub/cecil You need to download the following files corresponding to your architecture/OS: - one file with the common components (Vortex-Vortex-*.tar.gz) - one file for each front-end you are interested in (e.g., Vortex-Cecil-*.tar.gz) - the precompiled Vortex executable(s) for your architecture(s)/OS(es) (vortex-*..tar.gz), and/or the .c/.h source files for building Vortex for your architecture(s)' word-size(s) (Vortex-gen-*.c*.tar.gz) - optionally, any other front-end-specific precompiled binaries, e.g. the Cecil interpreter binary (cecil-*..tar.gz) 3) Uncompress and untar the downloaded files in $VORTEX_BASELINE; check file permissions For example: cd $VORTEX_BASELINE; tar zxBpvf Vortex-Vortex-*.tar.gz; ... Note: the files in the distribution come user- and group-writable, which is suitable for shared group projects. If this is inappropriate for you, you may want to run `chmod' or `chgrp' recursively on the distribution before proceeding. For example, to disable group-write: chmod -R g-w $VORTEX_BASELINE; umask 022 4) Edit $VORTEX_BASELINE/bin/shell/vortex.cshrc to configure your installation Change setenv VORTEX_BASELINE /projects/cecil/vortex-root/vortex to be setenv VORTEX_BASELINE (By default, the VORTEX_HOME environment variable will be set from VORTEX_BASELINE. If invididual users desire their own copy of the Vortex tree (as when working on Vortex under CVS), then VORTEX_HOME can be set manually to each user's copy. All Vortex scripts and programs use VORTEX_HOME as the root of the current copy of Vortex.) If the default definitions this script computes for VORTEX_MAKE (a GNU-make-like program), VORTEX_SH (a sh-compatible program), VORTEX_CSH (a csh-compatible program), VORTEX_TCSH (a tcsh-compatible program), or VORTEX_PERL (a perl-v.-5-compatible program) are not correct, then you can either change this file in place or bind them in your .cshrc/.bashrc as needed. If you don't have tcsh, set VORTEX_TCSH to the value of VORTEX_CSH instead, delete the 'if (-l $f) ...' test in $VORTEX_BASELINE/bin/shell/MakeScriptWrappers, and see the note below about the pm* scripts. If you don't have perl, then don't define this variable; you won't be able to run some support scripts, e.g. those for processing Vortex execution profiles.) You also can edit any of $VORTEX_BASELINE/bin/shell/vortex.{bashrc,zshrc} if these shells are used by users of the distribution. You can inspect what settings are computed by 'source'ing the version of this file that is right for your shell. If any settings are wrong, you should remove the settings, make changes, and re-source. 5) You may need to edit some of: (*) $VORTEX_BASELINE/runtime/makefiles/ArchConfig.$VORTEX_ARCH $VORTEX_BASELINE/runtime/makefiles/ArchConfig.default $VORTEX_BASELINE/runtime/makefiles/VortexConfig.$VORTEX_ARCH $VORTEX_BASELINE/runtime/makefiles/VortexConfig.default to redefine ARCH_CC, ARCH_CPLUSPLUS, and ARCH_AS if the default executable names or options are inappropriate for your site. You should not change any of the special -D command line arguments that are being passed to it. You also may need to adjust the list of libraries to link with (VORTEX_LINK_LIBS in VortexConfig.default) for different versions of gcc/g++. (*) $VORTEX_ARCH is the name denoting your architecture/OS - it is part of the name of the tar files that you download, and is also printed by $VORTEX_BASELINE/bin/shell/vortex-arch. See the instructions below if you're interested in porting Vortex to a new architecture/OS combination. 6) Execute $VORTEX_CSH -f $VORTEX_BASELINE/bin/shell/SETUP where $VORTEX_CSH is whatever it was set to after 'source'ing vortex.cshrc. SETUP will compile Vortex tools and libraries as necessary; this will take some time. If there are any problems, correct them and rerun SETUP again. If you want to force SETUP to run again on a given front-end, give it as an argument (use "Vortex" for the common components of the distribution). For example: $VORTEX_CSH -f $VORTEX_BASELINE/bin/shell/SETUP Vortex Cecil You can compare your output against the sample output in $VORTEX_BASELINE/notes/SETUP..sample-output. Certain differences are expected, such as dates, times, sizes, path names (especially $VORTEX_HOME), and architecture-specific names and compiler flags. Also, different sets of runtime libraries are compiled for different architectures. If you don't get the paths to your csh, perl, etc., right the first time, you will need to go to $VORTEX_BASELINE/{,*/}bin/$VORTEX_ARCH and manually remove any shell-script wrappers that SETUP creates there, before re-running SETUP. If the precompiled Vortex executable crashes, e.g. during SETUP of the Cecil or Java front-end, then it may be that you need to recompile it for your system from scratch. If you didn't already, download and unpack the Vortex-gen-*.cNN.tar.gz tarfile (where NN is either 32 or 64, the word size in bits of your machine), remove the $VORTEX_BASELINE/bin/$VORTEX_ARCH/vortex* executable, run SETUP Vortex to build the Vortex executable from its sources, and then rerun SETUP. If you get C/C++ compilation errors during SETUP, consult the Architecture/OS notes below. 7) If you want to enable parallel phase 2 compiles using pm, you need to edit the files $VORTEX_BASELINE/bin/shell/compileMachineNames and $VORTEX_BASELINE/bin/shell/linkMachineName to change the lists of UW-specific compute servers into lists of machines at your installation. Also, the scripts for parallel compiles, pm and pmwait (found in $VORTEX_BASELINE/bin/shell), are both currently written to use tcsh. If your site does not have tcsh, you can use csh instead (e.g., by defining VORTEX_TCSH to be $VORTEX_CSH), but you may have to always give pm/pmwait an explicit -d command line argument specifiying the directory in which the parallel compiles should be run. AFTER you finish the installation, you can start compiling/running with Vortex sample programs or your own programs, as described in the README files for each front-end. For Cecil programs, you can follow instructions in QUICK-START-CECIL, QUICK-START-VORTEX, or in the Vortex user manual. ------------- --- NOTES --- ------------- We use gcc/g++ (either 2.6.3, 2.7.2.1, 3.2, or 3.3) and gmake (either 3.71, 3.74, 3.75, or 3.79.1) to compile the C++ files produced by Vortex. Both gcc/g++ and gmake are available from ftp://prep.ai.mit.edu/pub/gnu. You may be able to use other compilers and make implementations successfully, however we recommend using gcc/g++ and gmake. It is possible to run Vortex on several different architectures using a single shared directory tree. To set up a multi-architecture shared tree, the above instructions are modified as follows: (1) Download and untar, in the same directory, the desired front-end tar files *for each architecture*. (2) Likewise, you can download and untar both Vortex-gen-*.c{32,64}.tar.gz tarfiles into your shared $VORTEX_BASELINE tree. (3) When modifying vortex.cshrc during the set-up process above, you may need to make the settings architecture-dependent, in a manner similar to how $VORTEX_BASELINE/bin/shell/vortex-arch works. (4) Run SETUP *on a machine of each architecture*. If you often use Vortex's utilities from your shell prompt, you may find it convenient to include the definitions in $VORTEX_BASELINE/bin/shell/vortex.cshrc in your shell environment, for example, by source'ing this file from your .cshrc. ------------------------------------------------ --- Architecture/OS/front-end-specific notes --- ------------------------------------------------ ** Notes for the x86/Linux release ** -- Our system has been compiled and run successfully on a number of different versions of Linux and gcc, but it may not work for all systems. OS-dependent issues are largely isolated to the following files: $VORTEX_BASELINE/runtime/os/src/os.[ch] $VORTEX_BASELINE/runtime/gc/conservative-gc/src/os_dep.c ** Notes for the x86/Windows release ** -- The system has been ported using the Cygwin suite of UNIX-like tools and libraries, available from http://www.cygwin.com. You need at least gcc/g++, make, tcsh, and perl, in addition to the basic cygwin tools. NOTE: GCC 4.x's optimizer seems to break our code, but GCC 3.3.x works. The system has been tested at various times on WinNT, Win95, Win98, Win2000, and WinXP. Since Windows+Cygwin isn't a full Unix, some support utilities may not work as well as they do under a real Unix. ** Notes for the Mac OS X release ** -- We have run this release on OS X v. 10.3 (Panther). It has only been minimally tested. ** Notes for other architecture/OS combinations ** -- Older versions of Vortex have been built on a number of other platforms beyond the few we currently have available to test on, including Sparc/SunOS 4.x, Sparc/Solaris 5.5.x, Sparc/Solaris 5.8, PowerPC/AIX, Alpha/OSF1, and HP-PA/HP-UX. You can try to install and SETUP Vortex normally on these systems, using the pregenerated C++ code for the Vortex executable in the Vortex-gen-*.c{32,64}.tar.gz tarfiles. If this doesn't work cleanly, then you can follow the instructions below for porting to a new architecture (step 2 is unnecessary). ** Porting to a new architecture/OS combination ** -- (Does not address non-Cecil front-ends.) 1) You should have gotten at least one of the Vortex-gen-*.cNN.tar.gz tarfiles, which contains pregenerated C++ code for the Vortex executable, and unpacked it into $VORTEX_BASELINE. 2) Define the arch/OS combination you want: Extend $VORTEX_BASELINE/bin/shell/vortex-arch to define a new architecture name (referred to henceforth as $VORTEX_ARCH). In the $VORTEX_BASELINE/runtime/makefiles directory, add VortexConfig.$VORTEX_ARCH and ArchConfig.$VORTEX_ARCH files based on the combinations already defined. In the $VORTEX_BASELINE/runtime/{pic,minimal}/src directories, add RuntimeMakefile.$VORTEX_ARCH files based on the ones already defined. 3) Port & build the make support programs "lock-run", "removeCRs", and "zap". Ideally, this should be as simple as going to the directory $VORTEX_BASELINE/bin/src and typing "$VORTEX_MAKE". If successful, the directory $VORTEX_BASELINE/bin/$VORTEX_ARCH should contain the "lock-run", "removeCRs", and "zap" executables. 4) Port & build the OS-dependent functions library. Go to the directory $VORTEX_BASELINE/runtime/os/src and type "$VORTEX_MAKE". If successful, the directory $VORTEX_BASELINE/runtime/os/$VORTEX_ARCH should contain the libos.a library. 5) Port & build the Boehm-Weiser conservative garbage collector. Again, in the best case this is a cd to the directory $VORTEX_BASELINE/runtime/gc/conservative/src followed by invoking "$VORTEX_MAKE". The directory $VORTEX_BASELINE/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. 6) You may want to try to build the Vortex threading library. Go to the directory $VORTEX_BASELINE/runtime/qvt/src and type "$VORTEX_MAKE". If successful, the directory $VORTEX_BASELINE/runtime/qvt/$VORTEX_ARCH should contain the libqvt.a library. "$VORTEX_MAKE test" builds and runs a threading test program. 7) You are finally ready to build the vortex executable. cd to $VORTEX_BASELINE/bin/vortex-gen-cNN. Source $VORTEX_BASELINE/bin/shell/vortex.cshrc (if your shell is csh-compatible; you can source .../vortex.bashrc if you're using bash or .../vortex.zshrc if you're using zsh) to set the VORTEX_* environment variables. Do "$VORTEX_MAKE clean; $VORTEX_MAKE depend; $VORTEX_MAKE". This should build an executable named vortex$VORTEX_EXE in the objects.$VORTEX_ARCH subdirectory. ($VORTEX_EXE is .exe on Cygwin and empty on Unix.) You may need to edit runtime system files (in $VORTEX_BASELINE/runtime/pic/src) to work around various OS-specific quirks. 8) cp/mv the objects.$VORTEX_ARCH/vortex$VORTEX_EXE executable to $VORTEX_BASELINE/bin/$VORTEX_ARCH/vortex$VORTEX_EXE 9) Edit $VORTEX_BASELINE/bin/shell/SETUP-Vortex with any additional architecture-specific cases as desired. Steps 3-8 above are the core of what SETUP-Vortex does automatically. You should now be ready to go. One way to test whether you've gotten your new system fully running is to cd to $VORTEX_BASELINE and execute "SETUP" to rebuild systematically all the support files of Vortex and the various front-ends you have downloaded. Doing SETUP on the Cecil, Diesel, or Java front-ends will also exercise the newly built Vortex executable. If you're willing to rebuild your own Vortex executable from the Cecil sources (i.e., use Vortex to compile the vortex.cecil application), you can add additional support to Vortex itself for your architecture by editing the current_C_architecture() method in the $VORTEX_BASELINE/Cecil/src/compiler/codegen/generic/arch-spec.cecil file. Please let us know of any changes you make to the system, so we can include them in future releases.