UW Cecil/Diesel/Vortex/Whirlwind Project Internal Documents

Project Ideas

Using Cecil, Diesel, and/or Vortex


The sources to the above manuals, plus Makefiles to rebuild them properly, are in /projects/cecil/cecil/doc/manuals.

WASP/Cecil Mail Logs

Setting Up Your Own Vortex Working Tree

Say you want to start working on the Cecil, Diesel, Vortex, or Whirlwind systems, and you need to build your own working tree, hanging off of our existing Vortex baseline and CVS repository. If you're building your tree on one of the department research machines, do the following:

If you're setting up a release on your home machine, you have a couple of options.


We use CVS to manage our versions and concurrent work.  Check-out is done with normal cvs update -d -P commands.  We have a script vortex-commit that we use as a wrapper around cvs commit, which also checks out a copy of the latest CVS tree into the directory /projects/cecil/vortex-root/vortex (which we call "the baseline").

If you will be looking at a lot of Cecil source code from the ${VORTEX_HOME}/Cecil/src/* directories, I recommend creating a directory ${VORTEX_HOME}/Cecil/src/links that contains symbolic links to all the .cecil files in the other directories, flattening out the directory hierarchy and putting all the source files in one convenient place. See ~chambers/cecil/links/MakeLinks for a script that (re)builds these links.  Likewise for Diesel source code in ${VORTEX_HOME}/Diesel/src/* directories; see ~chambers/diesel/links/MakeLinks for a script that (re)builds these links.

You probably want to set up ssh public-key login on your research account, enabling you to log in to any other research machine w/o entering a password by hand, so that you can make easy use of Vortex's parallel make facilities.

Exercising, Testing, and Benchmarking Whirlwind

A bunch of .wil files exist for exercising and regression-testing the Whirlwind compiler.

Many smaller tests are in $VORTEX_HOME/Diesel/src/whirlwind/tests.

A number of Java benchmarks have been collected, in $VORTEX_HOME/Java/src.  These benchmarks can be translated into WIL by going to their $VORTEX_HOME/Java/src/<benchmark-name>/wil subdirectory and executing the Jil-em script.  (The script is controlled by the Files, Classpath, MainName, and AppName files.  If you want to add your own Java benchmarks, which use only the subset of the Java 1.0.2 library that we support, create these files for your program and then run Jil-em.)  One that comes pre-translated into WIL is Towers of Hanoi, in $VORTEX_HOME/Java/src/example.  Its Java source is in .../example/src, the compiled Java .class files are in .../example/classes, and the WIL files translated from the .class files are in the .../example/wil.  The Java standard library classes also are already translated to WIL; those files are in $VORTEX_HOME/Java/wil-stdlib.  (WIL translations of all the benchmarks and the standard library classes can alternatively be found in /projects/cecil/WIL-src/Java/{<benchmark-name>,wil-stdlib}.)

To use WW to compile one of these benchmarks, you should put the directory containing the benchmark's .wil files and the directory containing the Java standard library classes' .wil files into WW's source path, e.g.:

Whirlwind> append source_paths $VORTEX_HOME/Java/src/<benchmark-name>/wil
Whirlwind> append source_paths $VORTEX_HOME/Java/wil-stdlib

Then you can compile the Java benchmark, e.g.:

Whirlwind> pmakeo2 <benchmark-name>.wil

An even bigger regression test is the make-whirlwind-profile script, which takes as its argument the path to the WW compiler executable to test, and uses it compile test.wil, towers.wil, a small Diesel program, and others, under many different optimization and target-code configurations (e.g. w/ and w/o RTA, for C or C-- output, w/ and w/o Rhodium opts, etc.).  This is the main check to see whether it's safe to CVS-commit a new WW version.  It also is the script used when building a new whirlwind.nCCP profile.

Finally, scripts exist for doing performance measurements of Whirlwind.  The main scripts are $VORTEX_HOME/Java/bin/shell/{Build,Run}-Whirlwind-Java-Benchmarks.  They should be run in a directory containing a symbolic link named whirlwind to the WW executable to use.  The Build script compiles all the Java benchmarks under a variety of configurations (and takes a long time); you can run this script repeatedly to make sure that things are up to date, and it won't recompile anything it's already compiled.  It writes a summary of its progress to a file named buildLog, but I usually redirect all its output to a log file too.  The Run script will then invoke the compiled benchmarks, running them 11 times and saving the resulting execution times to a file named whirlwind-java-data.db, and finally print out results using median execution times for all benchmarks and configurations, suitable for copying into a paper.  To get reliable timings, this script should be run on an otherwise unloaded, fast machine.  Again, I usually redirect this script's output to the same log file.  These scripts make use of other scripts, $VORTEX_HOME/bin/shell/{buildConfig,runConfig,showData}, which are controlled by the $VORTEX_HOME/bin/shell/configs.perl file.  You can add new optimization configurations for testing, or new named groups of benchmarks or configurations, by editing configs.perl, and optionally editing the {Build,Run}-Whirlwind-Java-Benchmarks scripts, e.g. as I've done to add the -cha option to the scripts that exercises the CHA-related configurations.  You also can explore the other options that are available to the underlying buildConfig, runConfig, and showData scripts by looking at the end of the configs.perl file.

Making a Release

See the file ${VORTEX_HOME}/notes/internal/for-release for instructions on how to make a new release.

Cecil/Vortex Project, chambers@cs.washington.edu