This is the README file for the Stanford SUIF compiler system. Please read this file in its entirety before building the SUIF system. TABLE OF CONTENTS: Copyright notice WHAT SUIF IS / WHAT SUIF IS NOT OTHER SOFTWARE THAT YOU WILL NEED CONTENTS OF THE DISTRIBUTION INSTALLATION INSTRUCTIONS USING THE SUIF SYSTEM OLD SUIF VS. NEW SUIF SUIF SUPPORT / MAILING LISTS GETTING STARTED WITH SUIF ********************************************************************** This software is Copyright (c) 1994 Stanford University. All rights reserved. Permission is given to use, copy, and modify this software for any non-commercial purpose as long as this copyright notice is not removed. All other uses, including redistribution in whole or in part, are forbidden without prior written permission. This software is provided with absolutely no warranty and no support. ********************************************************************** WHAT SUIF IS SUIF is a collection of programs and libraries, mostly written in C++, that allow researchers to investigate issues in scalar and parallel optimization. The SUIF distribution contains all the pieces necessary for a working compiler that will translate C or FORTRAN into either a MIPS (R3000) executable or back into C code (suitable for compiling with a native compiler). It contains passes to do a variety of transformations including parallel loop detection, parallel code generation, cache-based loop transformations, and scalar optimizations. The SUIF system will correctly compile most major benchmark suites. SUIF also provides a set of core libraries that (we hope) allow people to easily write new SUIF passes to investigate their favorite compiler research topic. WHAT SUIF IS NOT SUIF is not a production compiler. It is not suitable for replacing your native compiler. Don't even attempt to compile a kernel with it. SUIF does not have many code generators. SUIF will not generate scalar code that's as good as your native compiler (unless you use the "C" backend and actually compile with your native compiler...) If you are running a machine that is not MIPS-based, you will have to use the "C" backend and feed the result into your native C compiler (SUIF will do this automatically). SUIF is not supported software. It is distributed without warranty. We will do what we can to help you with problems, but in the end you're on your own. See the end of this file for information on mailing lists about SUIF. ********************************************************************** OTHER SOFTWARE THAT YOU WILL NEED The SUIF system uses a lot of software from the GNU project. Although you may be able to adapt it to work with other compilers, you'll save yourself a lot of trouble by using the programs specified below. These programs are available by anonymous ftp from one of the GNU ftp servers, such as prep.ai.mit.edu or gatekeeper.dec.com. Note that most of these packages have been compressed with the gzip program; you will have to compile and install gzip before you can uncompress the others. This is explained in greater detail in the README files on the ftp servers. The version numbers below reflect the versions that we are currently using. gzip 1.2.4 bison 1.22 gcc/g++ 2.5.8 libg++ 2.5.3 gmake 3.70 Also the GNU debugger will be helpful if you design your own SUIF applications: gdb 4.12 ********************************************************************** CONTENTS OF THE DISTRIBUTION This rest of this file describes the structure of the distribution, and tells how to compile and install the software. The "ReleaseNotes" file describes information specific to the current release. The "WhatsNew" file describes differences between SUIF releases. The "FAQ" file includes answers to commonly asked questions. The "src" directory contains the sources for all SUIF software. The "man" directory contains man pages for SUIF programs. The "docs" directory contains PostScript versions of the SUIF documentation. The "info" directory contains GNU Emacs info versions of the SUIF documentation. The "html" directory contains HTML (for the World Wide Web) versions of the SUIF documentation. The "src/examples" directory contains examples of simple SUIF passes and sample input files. These files are taken from various manuals. ********************************************************************** INSTALLATION INSTRUCTIONS The SUIF system is fairly machine-independent. So far we have compiled it successfully on MIPS-based DEC and SGI machines, Sun SPARC machines running SunOS, and on x86 machines running Linux. See the ReleaseNotes for current information on the status of SUIF under these and other systems. Depending on your platform, define the MACHINE environment variable as follows: MIPS-based DEC systems: MIPSEL MIPS-based SGI systems: SGI Sun SPARC systems running SunOS: SPARC Linux systems: LINUX Any other host: The processor type of the host (like "RS6000" or "CRAY3") SUIF will be installed in the hierarchy in which it is compiled. If you want it installed elsewhere, you will have to copy the binaries there after compilation is complete. Define the SUIFHOME environment variable to the top-level directory of the SUIF hierarchy. (This is the directory containing this README file). Now add $SUIFHOME/$MACHINE/bin to your path. It is essential that your path contain this directory when you begin installation because the installation needs to use scripts it will find there. You will need about 96 MB of disk space to compile and install SUIF. The compilation of the entire system lasts about four hours on a DECstation 5000. --- PostScript, GNU emacs "info", and HTML versions of the SUIF manuals are included in the SUIF distribution. You may wish to regenerate these manuals from the original source. In this case you can do the following: If you have the GNU emacs "info" package installed, you can set the environment variable BUILD_INFO, and new info files will be generated during installation. If you have the TeX software (including dvips) and "texinfo.tex" support file installed, you can set the environment variable BUILD_PS, and new PostScript manuals will be generated during installation. If you have the "texi2html" and "RosettaMan" converters installed, you can set the environment variable BUILD_HTML, and new HTML versions of the manuals will be generated during installation. It does not matter what value you set these environment variables to, only that they are set. --- To build and install: * Set the MACHINE variable. * Set the SUIFHOME variable. * Add $SUIFHOME/$MACHINE/bin to your path. * Change to the $SUIFHOME directory. You may want to edit the Makefile to modify the list of targets to install. For example, if you're using a SPARC platform there's no point in installing the MIPS code generator (mexp and mgen). * Run "gmake setup" * Run "gmake install" The "install" target will do a relatively quiet build/installation. Any errors that are encountered will be left in log files in the appropriate source directories. If you would prefer to watch the build/install interactively, you can use the "install-noisy" target instead. ********************************************************************** USING THE SUIF SYSTEM Once you have installed the system, there is one more environment variable that must be set in order to have a working compiler. This is the SUIFPATH variable that determines which directories will be searched for compiler binaries. Like other PATH variables, its value is a list of colon-separated directory names which are searched in order from left to right. Unless you have copied SUIF binaries to another location, the first thing on the list should be $SUIFHOME/$MACHINE/bin. You will also want to add other directories to your SUIFPATH so that scc, the driver that calls the various passes, can use passes that are installed on your system but not distributed as part of SUIF. The most critical of these is cpp, the ANSI C pre-processor. This is _not_ provided with SUIF, so it's up to you to make sure you have this included in your path. Many systems will have a cpp in /usr/lib. Note, however, that some systems use older pre-ANSI versions of cpp, so care must be taken. If you don't have a system ANSI cpp, or if you're not sure it's ANSI, it is recommended that you use the version that comes with gcc. Hint: the command "gcc -v" will show you which directory your installed version of gcc is using for its internal passes. We've found that if you cd to $(SUIFHOME)/$(MACHINE)/bin and then run the csh command: ln -s `gcc -v |& head -1 | cut -d' ' -f4 | sed -e 's/specs/cpp/'` a symlink will automatically be created to the cpp of the latest installed gcc. Remember to repeat this after installing a new gcc. As another example of the use of the SUIFPATH variable, if you plan to use the SUIF-to-C converter followed by some other C compiler as a portable back-end, you will want the directory containing that compiler in your SUIFPATH. At this point you should make sure that all the environment variables you've set for SUIF are going to be set automatically whenever you use SUIF. Typically that means putting them in your .login or .profile. The environment variables you should consider setting automatically are SUIFHOME, SUIFPATH, MACHINE, BUILD_INFO, BUILD_PS, BUILD_HTML, and your path. Now you're ready to start running the SUIF passes. You should start with scc, the driver that calls the other passes. See the scc man page for details. When you start to develop your own passes and link in the SUIF libraries, you will have to be careful about linking in the libraries that depend upon one another and the order in which they are specified; libraries cannot be linked in after other libraries that they use or the linker may already have discarded the needed symbols. These are the current dependences among the SUIF libraries (note that general, hawg, flow, math, deptest, and sharlit are not listed as they are part of the obsolete old SUIF system and should not be used in new programs): SUIF /|\ \ / | \ \---------------\ /---/ | \ \ / | \-----\ \ / | \ \ CHECK USEFUL NSHARLIT SIMPLE | BUILDER | SUIFMATH | DEPENDENCE | TRANSFORM This means, for example, that libbuilder depends on both libuseful and libsuif. So a program using the builder library should include a line LIBS = -lbuilder -luseful -lsuif in its Makefile. The various libraries also have initialization functions that must be called. Since they depend on one another, these initializations must be done in the correct order. Fortunately, the standard Makefiles will handle all of this automatically if you call start_suif() before using any of the libraries. ********************************************************************** OLD SUIF VS. NEW SUIF Within the past year, much of the SUIF system has been rewritten from scratch. The original SUIF system (now called "old SUIF") is obsolete, and the new SUIF system ("new SUIF", or just "SUIF") has taken its place. Unfortunately, there are some parts of the old SUIF system that were not converted due to lack of time or motivation. These include the scalar optimizer ("oynk") and the MIPS code generator ("mexp" and "mgen"). To support these old SUIF passes, the old SUIF libraries are included in the distribution. These libraries (deptest, flow, general, hawg, looptrans, math, and sharlit) are for backwards compatibility only and should never be used in newly written SUIF passes. They are completely incompatible with the new SUIF libraries (builder, check, dependence, nsharlit, simple, suif, suifmath, transform, and useful). So that old SUIF programs may be used, two conversion programs are provided. oldsuif converts a new SUIF file to an old SUIF file. newsuif converts an old SUIF file to a new SUIF file. Because the representation of the two file formats is different, these conversion programs may not be successful at preserving all information in a file when old SUIF passes are run between conversion. For example, some annotations may be lost. We hope at some point to completely eliminate old SUIF. Anyone wishing to help us with this (such as by writing a new code generator) is quite welcome to do so. ********************************************************************** SUIF SUPPORT / MAILING LISTS The SUIF compiler system is released without warranty or promise of support. Essentially you are on your own. However, there are a number of mailing lists devoted to SUIF that you may join. We recommend that you join at least the suif-announce mailing list, as notices of patch releases or new versions will be sent to this list. suif-talk@suif.stanford.edu is for the discussion of anything related to SUIF. It is for the use of SUIF users to talk amongst themselves. suif-bugs@suif.stanford.edu is for the submission of bugs to the SUIF development team. There is no guarantee that submitting a bug will cause that bug to be fixed. Users may add themselves to the suif-bugs list if they wish to monitor other users' bug reports. suif-announce@suif.stanford.edu is for the announcement of new versions of SUIF. To join any of these lists, send mail to "majordomo@suif.stanford.edu" with the body: subscribe list-name Sending a message with the body: help will send info on other commands you may use. The SUIF team also maintains a World Wide Web server that includes information about SUIF, hypertext versions of the SUIF documentation, and published papers written by members of the SUIF team. If you have access to a Web browser, such as NCSA Mosaic, you can use the URL: http://suif.stanford.edu ********************************************************************** GETTING STARTED WITH SUIF The paper "The SUIF Compiler System" is an introduction to SUIF, its purpose, and its limitations. It is available in the directory "docs/suif-overview.ps". The man page for "scc" is the next thing to read. "scc" is the driver that calls other SUIF passes. It may be used just like "cc" or "f77" to generate an executable from a source, although some of the command line options may be different from your native compiler. Man pages are also available for all SUIF programs. If you are interested in using SUIF's parallelizing capabilities, you should read the SUIF Parallelizing Compiler Guide in "docs/parguide.ps". If you are interested in developing SUIF passes, you should read the documentation for the SUIF library, "docs/suif.ps", and the SUIF Cookbook, "docs/cookbook.ps". The latter contains a variety of examples of simple SUIF programs. The source for these examples may also be found in the "src/examples" directory. Finally, if you are developing complex applications, you may also be interested in the documentation for the SUIFMATH library (docs/suifmath.ps), BUILDER library (docs/builder.ps), TRANSFORM library (docs/transform.ps), DEPENDENCE library (docs/dependence.ps), and the Linear Inequality Calculator (docs/lic.ps). ********************************************************************** The Stanford Compiler Group