README.suif

   1 This is the README file for the Stanford SUIF compiler system,
   2 version 1 posthumous release 1.3.0.1.  This
   3
   4 TABLE OF CONTENTS:
   5
   6         Copyright notice
   7         WHAT SUIF IS / WHAT SUIF IS NOT
   8         HOW SUIF IS DISTRIBUTED
   9         CURRENT PACKAGES
  10         OTHER SOFTWARE THAT YOU WILL NEED
  11         SUIF SUPPORT / MAILING LISTS
  12         GETTING STARTED WITH SUIF
  13
  14 **********************************************************************
  15
  16 This software is Copyright (C) 1994,95 Stanford University
  17
  18     All rights reserved.
  19
  20     NOTICE:  This software is provided ``as is'', without any
  21     warranty, including any implied warranty for merchantability or
  22     fitness for a particular purpose.  Under no circumstances shall
  23     Stanford University or its agents be liable for any use of, misuse
  24     of, or inability to use this software, including incidental and
  25     consequential damages.
  26
  27     License is hereby given to use, modify, and redistribute this
  28     software, in whole or in part, for any purpose, commercial or
  29     non-commercial, provided that the user agrees to the terms of this
  30     copyright notice, including disclaimer of warranty, and provided
  31     that this copyright notice, including disclaimer of warranty, is
  32     preserved in the source code and documentation of anything derived
  33     from this software.  Any redistributor of this software or
  34     anything derived from this software assumes responsibility for
  35     ensuring that any parties to whom such a redistribution is made
  36     are fully aware of the terms of this license and disclaimer.
  37
  38     "SUIF" is a trademark of Stanford University.
  39
  40 **********************************************************************
  41
  42 WHAT SUIF IS
  43
  44 SUIF is a collection of programs and libraries, mostly written in C++,
  45 that allow researchers to investigate issues in scalar and parallel
  46 optimization.  The SUIF distribution contains all the pieces necessary
  47 for a working compiler that will translate C or FORTRAN into either a
  48 MIPS (R3000) executable or back into C code (suitable for compiling
  49 with a native compiler).  It contains passes to do a variety of
  50 transformations including parallel loop detection, parallel code
  51 generation, cache-based loop transformations, and scalar
  52 optimizations.  The SUIF system will correctly compile most major
  53 benchmark suites.  SUIF also provides a set of core libraries that (we
  54 hope) allow people to easily write new SUIF passes to investigate
  55 their favorite compiler research topic.
  56
  57
  58 WHAT SUIF IS NOT
  59
  60 SUIF is not a production compiler.  It is not suitable for replacing
  61 your native compiler.  Don't even attempt to compile a kernel with it.
  62 SUIF does not have many code generators.  SUIF will not generate
  63 scalar code that's as good as your native compiler (unless you use the
  64 "C" backend and actually compile with your native compiler...)  If you
  65 are running a machine that is not MIPS-based, you will have to use the
  66 "C" backend and feed the result into your native C compiler (SUIF will
  67 do this automatically).  SUIF is not supported software.  It is
  68 distributed without warranty.  We will do what we can to help you with
  69 problems, but in the end you're on your own.  See the end of this file
  70 for information on mailing lists about SUIF.
  71
  72 **********************************************************************
  73
  74 HOW SUIF IS DISTRIBUTED
  75
  76 The SUIF system is now distributed in several different pieces.  Some
  77 pieces are more stable and others less so.  For example, the basic
  78 parallelization system is separated from the base SUIF system, so
  79 those who are interested in only the basic compiler infrastructure
  80 don't have to deal with all the overhead and greater instability of
  81 the parallelizer.  This allows frequently changing releases of the
  82 more experimental parts without affecting the continuity of the more
  83 stable parts of the system.  It also allows researchers at other sites
  84 to maintain and release their own pieces without having to coordinate
  85 with Stanford.
  86
  87 **********************************************************************
  88
  89 CURRENT PACKAGES
  90
  91 Here are the packages currently available (note that if you got this
  92 file from the basesuif package, the list here may not be the most
  93 recent one, since the basesuif package is not changed for every
  94 release of another SUIF package -- the current version of this
  95 README.suif file is available by anonymous ftp from
  96 suif.stanford.edu:/pub/suif/README.suif):
  97
  98         basesuif      1.3.0.1
  99             The base SUIF system, required before any of the other
 100             packages can be used.
 101
 102         simplesuif    1.3.0.1
 103             A simplified interface for SUIF for teaching compiler
 104             courses; requires basesuif.
 105
 106         suifbuilder   1.3.0.1
 107             A library built on top of SUIF providing another interface
 108             for building SUIF code; requires basesuif.
 109
 110         baseparsuif   1.3.0.1
 111             The basic SUIF parallelization system; requires basesuif
 112             and suifbuilder.
 113
 114         fortback      1.3.0.1
 115             A SUIF-to-Fortran converter, to convert to a combination
 116             of Fortran and C to improve performance over conversion to
 117             C alone; requires basesuif.
 118
 119         suifcookbook  1.3.0.1
 120             An introduction to construction of SUIF passes in
 121             ``cookbook'' form, going through several examples;
 122             requires basesuif, suifbuilder, and baseparsuif.
 123
 124         suifcallgraph 1.3.0.1
 125             A call-graph library for SUIF; requires baseparsuif and
 126             basesuif.
 127
 128         suifvbrowser  1.3.0.1
 129             The SUIF Visual Browser: a graphical user interface to
 130             view SUIF files and their relations to input and output
 131             source code; requires suifcallgraph, baseparsuif, and
 132             basesuif, and also requires TCL/TK, a pair of packages
 133             that are available independently of SUIF.
 134
 135         oldsuif       6.0.0.beta.2
 136             Some remenants of an obsolete old SUIF system, with
 137             converters between ``old SUIF'' and modern SUIF, to
 138             provide some functionality that exists in the old system
 139             but not yet in modern SUIF in quite the same way; requires
 140             basesuif.  This hasn't been tested recently, since it uses
 141             obsolete C++ syntax which modern compilers don't like.  It
 142             may still work for some.
 143
 144 NOTE: All versions here are not very well tested in their current build
 145   configuration, although the bulk of the code has been in use at Stanford
 146   for years.  Nevertheless, there will certainly be build problems on
 147   many machine/compiler combinations.  We welcome your feedback about
 148   combinations that do and don't work and/or patches required.
 149   Consider this a ``beta'' release.
 150
 151 These packages are available by anonymous ftp from
 152 suif.stanford.edu:/pub/suif.  The filename is in the form
 153 <package-name>-<version>.tar.{gz|Z}.  Signed pgp certificates for all
 154 packages are also available in the same directory with the suffix .asc
 155 appended to the compressed tar file name.
 156
 157 **********************************************************************
 158
 159 OTHER SOFTWARE THAT YOU WILL NEED
 160
 161 The SUIF system uses a lot of software from the GNU project.  Although
 162 you may be able to adapt it to work with other compilers, you'll save
 163 yourself a lot of trouble by using the programs specified below.
 164 These programs are available by anonymous ftp from one of the GNU ftp
 165 servers, such as prep.ai.mit.edu or gatekeeper.dec.com.  Note that
 166 most of these packages have been compressed with the gzip program; you
 167 will have to compile and install gzip before you can uncompress the
 168 others.  This is explained in greater detail in the README files on
 169 the ftp servers.  The version numbers below reflect the versions that
 170 we are currently using.
 171
 172         gzip                            1.2.4
 173         bison                           1.22
 174         gmake                           3.73
 175         perl                            5.004
 176
 177 You'll also need a C/C++ compiler to compiler SUIF.  SUIF should
 178 compile without too much difficulty on any modern C++ compiler.
 179 Unfortunately, all too many C++ compilers are still based on cfront
 180 and do not use modern C++ syntax, so they will not work with SUIF.
 181 The following compilers are known to work with SUIF:
 182
 183     A. On any system:
 184
 185         gcc/g++                         2.7.2.3
 186         libg++                          2.7.1
 187
 188     B. On Silicon Graphics Irix systems:
 189
 190         SGI IRIX 5.3 C/C++ compiler
 191
 192     C. On SPARC or x86 Solaris systems:
 193
 194         SunSoft ProCompiler C++         4.2
 195
 196 Also a debugger will be helpful if you design your own SUIF
 197 applications.  On most systems, the GNU debugger is useful:
 198
 199         gdb                             4.15.1
 200
 201 **********************************************************************
 202
 203 SUIF SUPPORT / MAILING LISTS
 204
 205 The SUIF compiler system is released without warranty or promise of
 206 support.  Essentially you are on your own.  However, there are a
 207 number of mailing lists devoted to SUIF that you may join.  We
 208 recommend that you join at least the suif-announce mailing list, as
 209 notices of patch releases or new versions will be sent to this list.
 210
 211 suif-talk@suif.stanford.edu is for the discussion of anything related
 212 to SUIF.  It is for the use of SUIF users to talk amongst themselves.
 213
 214 suif-bugs@suif.stanford.edu is for the submission of bugs to the SUIF
 215 development team.  There is no guarantee that submitting a bug will
 216 cause that bug to be fixed.  Users may add themselves to the suif-bugs
 217 list if they wish to monitor other users' bug reports.
 218
 219 suif-announce@suif.stanford.edu is for the announcement of new
 220 versions of SUIF.
 221
 222 To join any of these lists, send mail to "majordomo@suif.stanford.edu"
 223 with the body:
 224
 225 subscribe list-name
 226
 227 Sending a message with the body:
 228
 229 help
 230
 231 will send info on other commands you may use.
 232
 233
 234 The SUIF team also maintains a World Wide Web server that includes
 235 information about SUIF, hypertext versions of the SUIF documentation,
 236 and published papers written by members of the SUIF team.  If you have
 237 access to a Web browser, such as NCSA Mosaic, you can use the URL:
 238
 239 http://suif.stanford.edu
 240
 241 **********************************************************************
 242
 243 GETTING STARTED WITH SUIF
 244
 245 If you haven't already, you should obtain the basesuif package and
 246 untar it.  Then look in the src/basesuif directory for the
 247 README.basesuif file and follow the instructions found therein.
 248
 249 **********************************************************************
 250
 251                         The Stanford Compiler Group