Read Me

{\rtf1\ansi\ansicpg1252\cocoartf2709
\cocoatextscaling0\cocoaplatform0{\fonttbl\f0\fnil\fcharset0 Calibri-Bold;\f1\fnil\fcharset0 Calibri;}
{\colortbl;\red255\green255\blue255;\red0\green0\blue255;}
{\*\expandedcolortbl;;\csgenericrgb\c0\c0\c100000;}
\paperw11900\paperh16840\margl1440\margr1440\vieww21620\viewh18620\viewkind1\viewscale200
\deftab720
\pard\pardeftab720\ri0\partightenfactor0

\f0\b\fs24 \cf0 README FILE FOR SPIM, XSPIM, PCSPIM, and QTSPIM \
\pard\pardeftab720\ri0\partightenfactor0

\f1\b0 \cf0 \
This directory contains SPIM--an assembly language MIPS32 simulator.\
\
SPIM is Copyright (c) 1990-2023, by James R. Larus.\
All rights reserved.\
\
SPIM is distributed under a BSD license:\
\
     Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\
\
     Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\
\
     Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials is provided with the distribution.\
\
     Neither the name of the James R. Larus nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.\
\
     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\
\
\
QtSPIM is linked to the Qt library, which is distributed under the GNU Lesser General Public License version 3 and GNU Lesser General Public License version 2.1.\
\
GNU Lesser General Public License, version 2.1\
\pard\pardeftab720\li720\ri0\partightenfactor0
{\field{\*\fldinst{HYPERLINK "http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html"}}{\fldrslt \cf0 http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html}}\
\pard\pardeftab720\ri0\partightenfactor0
\cf0 GNU Lesser General Public License, version 3\
\pard\pardeftab720\li720\ri0\partightenfactor0
{\field{\*\fldinst{HYPERLINK "http://www.gnu.org/licenses/lgpl-3.0.html"}}{\fldrslt \cf0 http://www.gnu.org/licenses/lgpl-3.0.html}}\
\pard\pardeftab720\ri0\partightenfactor0
\cf0 \
\pard\pardeftab720\ri0\partightenfactor0

\f0\b \cf0 GETTING SPIM SOURCE\
\pard\pardeftab720\ri0\partightenfactor0

\f1\b0 \cf0 \
Spim is hosted on SourceForge and its source code is available through SVN:\
\pard\pardeftab720\li720\ri0\partightenfactor0
{\field{\*\fldinst{HYPERLINK "https://sourceforge.net/projects/spimsimulator/"}}{\fldrslt \cf0 https://sourceforge.net/projects/spimsimulator/}}\
\pard\pardeftab720\ri0\partightenfactor0
\cf0 \
\
\pard\pardeftab720\ri0\partightenfactor0

\f0\b \cf0 DIRECTORIES\
\pard\pardeftab720\ri0\partightenfactor0

\f1\b0 \cf0 \
The subdirectories can be divided into two categories.\
\
1. Common to all versions of Spim:\
\
    CPU -- Contains the MIPS simulator and some utility functions common to all version of the simulator.\
\
    Documentation -- Contains the man pages, web page, and other documentation.\
\
    bin -- Utilities.\
\
    Setup -- Contain tools used to build deployable versions of the simulators.\
\
    Tests -- Contains regression test for the simulator.\
\
\
2. Front-ends for different versions of Spim:\
\
    PCSpim -- Microsoft Windows front end for Spim. [Obsolete]\
\
    QtSpim -- Preferred front end for Spim that works on Microsoft Windows, Linux, and Mac OS X.\
\
    spim -- Text-only (terminal or console) front end for Spim. Works on all platforms.\
\
    xspim -- X-Windows front end for Spim. Works on Linux and Mac OS X. (Built on a very old X Windows library that is no longer supported by the Mac.) [Obsolete]\
\
\
\pard\pardeftab720\ri0\partightenfactor0

\f0\b \cf0 BUILDING QTSPIM\
\pard\pardeftab720\ri0\partightenfactor0

\f1\b0 \cf0 \
It is generally not necessary to build QtSpim as the Spim website contains an installable version for most systems.\
\
Install the bison parser generator and flex lexer generator, either using Cygwin on Windows or native version on Linux and OS X.\
\
1. Download the free (open source) version of Qt Creator from {\field{\*\fldinst{HYPERLINK "http://qt.io"}}{\fldrslt http://qt.io}}. This is a large download that might take a while.\
   I have been using version 5.5, though any of the version 5.x should work fine. The 4.x releases will cause problems because of incompatible changes to the libraries. The 6.x releases also do not compiler out-of-the-box because of backwardly incompatible changes in version 6.\
\
        The open source version of Qt Creator for Windows, which uses mingw, works fine, as does the version that uses Microsoft Visual Studio's C++ compiler.\
\
        The Qt Creator package for Ubuntu is typically several releases behind, which can cause some problems with QtSPIM. Download a recent version from {\field{\*\fldinst{HYPERLINK "http://qt.io"}}{\fldrslt http://qt.io}}.\
\
2. Start QtCreator and configure the project to use whichever compilers are available on your system. gcc, llvm, and mdvc all work, though some of them generate some warnings at high optimization levels (yes, I should fix them).\
\
3. Build QtSpim.\
\
        If you are porting to a new system and see a large number of compiler errors in QtCreator, changes are good that you need to change QtSpim.pro to define the compiler flag that says "treat all files, including .c files, as C++ code. This flag is "-X C++" for gcc and "-TP" for the Microsoft compiler.\
\
4. Packaging QtSpim for distribution is a complex, OS-specific operation. The Setup directory contains the files for all three platforms. \
\
	On OS X, you need to run the script bin/release-osx and use the free Packages tool ({\field{\*\fldinst{HYPERLINK "http://s.sudre.free.fr/Software/Packages/about.html"}}{\fldrslt http://s.sudre.free.fr/Software/Packages/about.html}}).\
\
	On Windows,you need a copy of Visual Studio and the free version of WiX.\
\
	On Linux, the script bin/release-debian handles the entire process.\
\
On all three systems, the packaged version of QtSpim includes all the libraries and plugins used by QtSpim and assistant (the Qt help file viewer). Previously, the Linux used dependencies to bring in other packages that contained these libraries, but I cannot find the packages that contain all of these files for Qt5, so it is easier just to redistribute everything.\
\
\
\pard\pardeftab720\ri0\partightenfactor0

\f0\b \cf0 BUILDING SPIM and XSPIM\
\pard\pardeftab720\ri0\partightenfactor0

\f1\b0 \cf0 \
It is necessary to build spim and xspim, as they are only distributed as source.\
\
   1. Download the source for spimsimulator from sourceforge {\field{\*\fldinst{HYPERLINK "https://sourceforge.net/projects/spimsimulator/"}}{\fldrslt https://sourceforge.net/projects/spimsimulator/}}).\
\
   2. Decompress the file, using either the program uncompress for the first file or gzip for the second file:\
\
          % uncompress spim.tar.Z\
\
      or\
\
          % gzip -d spim.tar.gz\
\
   3. Move the file spim.tar to the directory in which you want to build spim and untar it:\
\
          % tar xf spim.tar\
\
      It will create a directory named spim-8.0 (or the most recent version number).\
\
   4. The simple terminal interface is contained in the spim-8.0/spim directory and the X-windows interfaces is in the spim-8.0/xspim directory. The other directories are described in the README file.\
\
   5. Next, you must set the directories in which spim will be installed by editing the Makefile (the file that contains instructions on building spim). In general, if you are installing spim and want the windowing version (xspim), edit the file xspim/Imakefile. If you don't want xspim or are running on a system without X-windows installed, you use the file spim/Makefile.\
\
      The programs are installed in standard locations, but you can change the pathnames to other locations:\
\
          EXCEPTION_DIR -- The full pathname of the directory in which to install the spim exception handler (exceptions.s).\
\
          BIN_DIR -- The full pathname of the directory in which spim and xspim should be installed.\
\
          MAN_DIR -- The full pathname of the directory in which the manual pages for spim and xspim should be installed.\
\
      In general, the remaining parameters in a Makefile need not be changed.\
\
   6. Then, if you are building xspim, change to the spim-8.0/xspim directory and type:\
\
          % xmkmf\
          % make\
\
      If you do not have a copy of xmkmf, you can use the Makefile in the xspim directory, but beware that it may not work on your system because the paths to the X windows libraries could be different.\
\
   7. If you do not have X-windows, change to thespim-8.0/spim directory, edit Makefile, and type:\
\
          % make\
\
   8. To run spim or xspim, the exception handler must be installed in the directory specified by the variable EXCEPTION_DIR in the Makefile. If the file exception.s is not installed, spim and xspim fail before they start running. You can either install this file by hand or by typing:\
\
          % make install\
\
   which also installs spim or xspim, and the manual pages in the directories that you set (above). You may need root permission to install these files, in which case type:\
\
          % sudo make install\
\
   9. To test that spim is correctly built, change to the spim-8.0/spim directory and type:\
\
          % make test\
\
      and examine the output of the test. (Note: the exception handler must be installed before running the test.)\
\
\
\pard\pardeftab720\ri0\partightenfactor0

\f0\b \cf0 BUILDING PCSPIM\
\pard\pardeftab720\ri0\partightenfactor0

\f1\b0 \cf0 \
It is not necessary to compile PCSpim (the Microsoft Windows version), as the Spim website\
contains a precompiled version.\
\
The Microsoft Windows version of Spim is called PCSpim and is built using Microsoft Visual\
Studio.\
\
spim (the terminal version) works well on Microsoft Windows. You can easily build it using the Cygwin port of the GNU tools (see {\field{\*\fldinst{HYPERLINK "http://www.cygwin.com"}}{\fldrslt \cf2 \ul \ulc2 www.cygwin.com}}).\
\
\
\pard\pardeftab720\ri0\partightenfactor0

\f0\b \cf0 NEW VERSIONS OF SPIM\
\pard\pardeftab720\ri0\partightenfactor0

\f1\b0 \cf0 \
I used to release the new versions of SPIM once a year, before a semester boundary (late August or early January). The new versions are available on:\
\
		{\field{\*\fldinst{HYPERLINK "https://sourceforge.net/projects/spimsimulator/"}}{\fldrslt https://sourceforge.net/projects/spimsimulator/}}\
\
\pard\pardeftab720\ri0\partightenfactor0

\f0\b \cf0 SPIM is no longer supported. The code has been stable for many years, with a few occasional bugs. But, as I reach retirement, it is clear to me that SPIM should retire as well. Feel free to fork a copy and fix the bugs yourself! }